Copy edit pass over /src/***.md #1474

kwalrath · 2019-04-22T04:06:06Z

My aim was to fix the YAML at the top of every file, in particular titles. As you might expect, the scope grew, since this was the first time I'd edited every single .md file.

Use includes for web & server tutorials, so we can reuse the cards in /tutorials/web & tutorials/server. Also regularize page titles.

Improve titles, tweak text.

Edited every .md file under the /src directory. For most pages, I just made the titles look right, but I made some other changes I'll describe later. (For now, I just want to back up my work!)

kwalrath · 2019-04-23T00:10:33Z

Here are the changes I made. I looked at every .md file under src and did the following:

Reviewed the YAML at the top of each file. As appropriate:
- Made the title sentence case; renamed if necessary to match the IA.
- Removed unnecessary quotation marks.
- Removed unnecessary key:value pairs (e.g. some occurrences of layout, obsolete, css, permalink). When I removed obsolete, sometimes added a note with caveats/background.
- Improved descriptions.
Labeled to-do items that I noticed:
- Added "TBD" when a page absolutely needs to be updated (or question answered) before we ship this.
- Added "PENDING" when we should make a change, but it isn't as urgent.
Tweaked the sidenav, adding /tools/pub/environment-variables and /tools/dartpad, and adding to & organizing Resources.
Removed some very obsolete/unused/unlinked pages:
- reflections-with-mirrors
- author pages
- synonyms placeholder
Fixed some but not all references to page names in content. We'll need another pass for this in another PR.
Revamped some tutorial pages:
- Created include files for content used in multiple pages: server-tutorials, web-tutorials. Could do more here.
- Revamped the tutorial index (/tutorials) and added server-side & web tutorials to the page.
- Added /tutorials/web (for URL walkers).
- Added more context for low-level HTML tutorials.
Rewrote /tutorials/server/get-started to not be Webstorm-specific.
Made changes to some other non-linked-to pages (ones people usually encounter by walking up the URL tree), such as articles/language and articles/libraries. Added /web.
Updated /community, removing links to disused destinations.
Made some other content changes to individual pages, including the spec page, /guides/libraries/futures-error-handling, ... I tried to restrain myself.

mit-mit · 2019-04-23T12:44:05Z

src/_articles/index.md

 title: Articles
-description: "Read about the Dart language and tools with this collection of articles, style guides, and more."
-permalink: /articles
+description: Read early articles about the Dart language and libraries.


Should we consider not having this page? It's already marked Obsolete.

If we delete or move every file under /articles, then yes.

Oh, didn't realize that this was the only way of getting to them

I don't actually link to this page or most of the articles, iirc, but if people find an article, they're likely to walk up the URL chain. We don't have to list articles we don't want people to visit, but I'd like to have a page to avoid unnecessary 404s.

mit-mit · 2019-04-23T12:47:11Z

src/_articles/server/benchmarking.md

 ---

 _Written by John McCutchan <br>
 October 2012 (updated November 2012; note updated July 2018)_

 <aside class="alert alert-warning" markdown="1">
-  This article still has valid information, but it was initially targeted for
+  This article was initially targeted for


I think we should retire this, and file a bug to produce a more contemporary version later

Filed #1475 and have removed it from my repo.

mit-mit · 2019-04-23T13:10:47Z

src/_includes/server-tutorials.md

@@ -0,0 +1,17 @@
+The following tutorials show how to develop scripts, command-line apps,


I think we are going to have to split this into command-line apps, and server apps. But we can do that in a later PR after more planning and discussion.

mit-mit · 2019-04-23T13:24:32Z

src/_tutorials/server/get-started.md

-    need to set the path to the SDK.
-    You can find the instructions at
-    [Configuring Dart support]({{site.webdev}}/tools/webstorm#configuring-dart-support).
+If you're using a Dart-savvy IDE, follow these instructions:


Consider linking 'Dart-savvy IDE' to some page that lists IDEs that are

Done in my repo.

mit-mit · 2019-04-23T14:02:32Z

src/tools/dartfmt.md

@@ -42,4 +42,13 @@ $ dartfmt --help

 {% comment %}
 [PENDING: Add info on commonly used options.]
+
+[PENDING: Advocate using this! Perhaps steal the first paragraph from


I wrote this a while back; may serve as inspiration
https://flutter.dev/docs/development/tools/formatting

Almost all of this content is applicable to Dart formatting, in general. Maybe we should have includes under site-shared? Or move this information to the Dart site?

I thought there might be a lint or other tool to help with trailing commas, but looking at the reported issues (dart-lang/dart_style#753, dart-lang/sdk#27086), it's apparently a hard problem to solve.

Filed #1475 to remind us to replace it.

kwalrath · 2019-04-23T18:21:01Z

@mit-mit I plan to commit this once the build passes, unless you think that's a problem.

I looked at every .md file under src and did the following: * Reviewed the YAML at the top of each file. As appropriate: * Made the title sentence case; renamed if necessary to match the IA. * Removed unnecessary quotation marks. * Removed unnecessary key:value pairs (e.g. some occurrences of layout, obsolete, css, permalink). When I removed obsolete, sometimes added a note with caveats/background. * Improved descriptions. * Labeled to-do items that I noticed: * Added "TBD" when a page absolutely needs to be updated (or question answered) before we ship this. * Added "PENDING" when we should make a change, but it isn't as urgent. * Tweaked the sidenav, adding /tools/pub/environment-variables and /tools/dartpad, and adding to & organizing Resources. * Removed some very obsolete/unused/unlinked pages: * reflections-with-mirrors * author pages * synonyms placeholder * Fixed some but not all references to page names in content. We'll need another pass for this in another PR. * Revamped some tutorial pages: * Created include files for content used in multiple pages: server-tutorials, web-tutorials. Could do more here. * Revamped the tutorial index (/tutorials) and added server-side & web tutorials to the page. * Added /tutorials/web (for URL walkers). * Added more context for low-level HTML tutorials. * Rewrote /tutorials/server/get-started to not be Webstorm-specific. * Made changes to some other non-linked-to pages (ones people usually encounter by walking up the URL tree), such as articles/language and articles/libraries. Added /web. * Updated /community, removing links to disused destinations. * Made some other content changes to individual pages, including the spec page, /guides/libraries/futures-error-handling, ... I tried to restrain myself.

kwalrath added 3 commits April 21, 2019 12:57

List all tutorials in /tutorials

af4d65a

Use includes for web & server tutorials, so we can reuse the cards in /tutorials/web & tutorials/server. Also regularize page titles.

Tweaks to /codelabs and /samples

622a34b

Improve titles, tweak text.

Copy edit pass

d3871d2

Edited every .md file under the /src directory. For most pages, I just made the titles look right, but I made some other changes I'll describe later. (For now, I just want to back up my work!)

googlebot added the cla: yes Contributor has signed the Contributor License Agreement label Apr 22, 2019

fix build

e91544c

kwalrath requested a review from mit-mit April 23, 2019 00:10

kwalrath changed the title ~~[WIP] Copy edit pass over /src/***.md~~ Copy edit pass over /src/***.md Apr 23, 2019

mit-mit reviewed Apr 23, 2019

View reviewed changes

kwalrath added 2 commits April 23, 2019 11:14

Remove the benchmarking article

cb2063e

Filed #1475 to remind us to replace it.

reviewer-suggested tweak to get-started

e58d250

kwalrath merged commit f93b3a4 into dash Apr 23, 2019

kwalrath deleted the kw-dash-titles branch April 23, 2019 20:58

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Copy edit pass over /src/***.md #1474

Copy edit pass over /src/***.md #1474

kwalrath commented Apr 22, 2019 •

edited

Loading

kwalrath commented Apr 23, 2019 •

edited

Loading

mit-mit Apr 23, 2019

kwalrath Apr 23, 2019

mit-mit Apr 23, 2019

kwalrath Apr 23, 2019

mit-mit Apr 23, 2019

kwalrath Apr 23, 2019

mit-mit Apr 23, 2019

mit-mit Apr 23, 2019

kwalrath Apr 23, 2019

mit-mit Apr 23, 2019

kwalrath Apr 23, 2019

kwalrath commented Apr 23, 2019

		@@ -0,0 +1,17 @@
		The following tutorials show how to develop scripts, command-line apps,

Copy edit pass over /src/***.md #1474

Copy edit pass over /src/***.md #1474

Conversation

kwalrath commented Apr 22, 2019 • edited Loading

kwalrath commented Apr 23, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kwalrath commented Apr 23, 2019

kwalrath commented Apr 22, 2019 •

edited

Loading

kwalrath commented Apr 23, 2019 •

edited

Loading