doc: update synopsis, toc, other nits #6167

Fishrock123 · 2016-04-12T17:39:36Z

Checklist

tests and code linting passes
documentation is changed or added
the commit message follows commit guidelines

Affected core subsystem(s)

doc

Description of change

There are a few things here:

Updated the Example to be more modern and better reflect the example in https://nodejs.org/en/about/
Renamed Synopsis to Usage & Example
Node.js(1) in the TOC is now Node.js since the former does not make sense in any context
The TOC is now subdivided: general about, subsystems, extra links
Added a toc / sidebar link to the repo/issue tracker and also the mailing list

cc @nodejs/documentation

jasnell · 2016-04-12T17:44:43Z

LGTM

Fishrock123 · 2016-04-12T17:46:15Z

Here's some rendering of the toc subdivisions, tested on chrome, ff, safari:

Fishrock123 · 2016-04-12T17:47:21Z

Hmm, looks like I wasn't quite accurate with those shots. The lines do have the same relative margin on both sides in the sidebar.

Knighton910 · 2016-04-12T17:57:15Z

👍

benjamingr · 2016-04-12T17:58:53Z

doc/api/_toc.markdown

@@ -1,7 +1,10 @@
 @// NB(chrisdickinson): if you move this file, be sure to update tools/doc/html.js to
 @// point at the new location.
 * [About these Docs](documentation.html)
-* [Synopsis](synopsis.html)
+* [Synopsis & Example](synopsis.html)


I'm not sure about that

That file is not a synopsis of anything.

Example doesn't really describe much.

What about "Hello World" or "Usage" or something like that?

benjamingr · 2016-04-12T18:01:15Z

Two nits, generally LGTM

trevnorris · 2016-04-12T22:17:52Z

doc/template.html

@@ -13,7 +13,7 @@
    <div id="column2" class="interior">
      <div id="intro" class="interior">
        <a href="/" title="Go back to the home page">
-          Node.js (1)
+          Node.js


It would be more appropriate to be NODE(1).

nm. wasn't paying attention to what file this was located in. our man page should be NODE(1), but this looks good.

Our man page is NODE(1) since I rewrote it. :P

Fishrock123 · 2016-04-15T14:52:47Z

@benjamingr Updated, ptal.

@bengl have time to take a look?

Fishrock123 · 2016-04-15T14:53:57Z

As a note, I didn't rename the filename for synopsis.markdown since I didn't really want to bikeshed it here, but perhaps intro is a better name for the file.

bengl · 2016-04-15T16:24:48Z

doc/api/synopsis.markdown

@@ -1,29 +1,43 @@
-# Synopsis
+# Usage


The title being different from the filename is potentially concerning, as mentioned already in a comment.

Could the filename be changed, and then a redirect added in synopsis.html to preserve links?

Fishrock123 · 2016-04-27T16:29:16Z

@nodejs/documentation could we get some more opinions here about the file name/title thing?

Fishrock123 · 2016-04-27T16:29:58Z

Also, if we can leave that for a later PR, that would be great; I'd really like to get some of this merged.

eljefedelrodeodeljefe · 2016-04-27T16:37:26Z

doc/api/synopsis.md

+Please see the [Command Line Options][] document for information about
+different options and ways to run scripts with Node.
+
+## Hello World Example


I'd prefer Hello World or "Hello World!" or nothing at all.

eljefedelrodeodeljefe · 2016-04-27T16:37:51Z

LGTM w/ nits.

Fishrock123 · 2016-04-27T21:32:34Z

Updated, ## Hello World Example is now just ## Example.

eljefedelrodeodeljefe · 2016-04-27T21:35:20Z

👍 done deal then.

kahwee · 2016-04-27T21:56:55Z

LGTM

jasnell · 2016-04-29T06:29:01Z

doc/api/synopsis.md

 ```

 To run the server, put the code into a file called `example.js` and execute
-it with the node program
+it with Node.


nit: s/Node/Node.js

Maybe better as node example.js?

that works too

Nvm, that's on the lines below

nodejs#6167 Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Robert Jefe Lindstädt <[email protected]>

Node.js(1) does not make sense. Node(1) would, but this isn’t a `man` page. nodejs#6167 Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Robert Jefe Lindstädt <[email protected]>

MylesBorins · 2016-06-01T23:49:37Z

looks like this relies on some changes not in v4.x

@Fishrock123 please feel free to send a pr if you want to backport this

Fishrock123 · 2016-06-02T17:54:20Z

@thealphanerd This lands cleanly for me on v4.x-staging.

PR-URL: #6167 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Robert Jefe Lindstädt <[email protected]>

Node.js(1) does not make sense. Node(1) would, but this isn’t a `man` page. PR-URL: #6167 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Robert Jefe Lindstädt <[email protected]>

PR-URL: #6167 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Robert Jefe Lindstädt <[email protected]>

MylesBorins · 2016-06-02T18:06:54Z

@Fishrock123 must have caught the missing bits in other backports yesterday. thanks for checking

PR-URL: #6167 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Robert Jefe Lindstädt <[email protected]>

Node.js(1) does not make sense. Node(1) would, but this isn’t a `man` page. PR-URL: #6167 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Robert Jefe Lindstädt <[email protected]>

PR-URL: #6167 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Robert Jefe Lindstädt <[email protected]>

Node.js(1) does not make sense. Node(1) would, but this isn’t a `man` page. PR-URL: #6167 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Robert Jefe Lindstädt <[email protected]>

PR-URL: #6167 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Robert Jefe Lindstädt <[email protected]>

Node.js(1) does not make sense. Node(1) would, but this isn’t a `man` page. PR-URL: #6167 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Robert Jefe Lindstädt <[email protected]>

PR-URL: #6167 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Robert Jefe Lindstädt <[email protected]>

Fishrock123 added the doc Issues and PRs related to the documentations. label Apr 12, 2016

Fishrock123 changed the title ~~Modernize docs~~ doc: update synopsis, toc, other nits Apr 12, 2016

benjamingr reviewed Apr 12, 2016
View reviewed changes

trevnorris reviewed Apr 12, 2016
View reviewed changes

Fishrock123 force-pushed the modernize-docs branch from e561107 to 2953a06 Compare April 15, 2016 14:52

bengl reviewed Apr 15, 2016
View reviewed changes

estliberitas force-pushed the master branch 2 times, most recently from 7da4fd4 to c7066fb Compare April 26, 2016 05:23

Fishrock123 force-pushed the modernize-docs branch from 2953a06 to b70e5d6 Compare April 27, 2016 16:30

eljefedelrodeodeljefe reviewed Apr 27, 2016
View reviewed changes

Fishrock123 force-pushed the modernize-docs branch from b70e5d6 to ec46ff1 Compare April 27, 2016 21:32

jasnell reviewed Apr 29, 2016
View reviewed changes

Fishrock123 force-pushed the modernize-docs branch from ec46ff1 to a4c4e58 Compare April 29, 2016 17:15

Fishrock123 added 2 commits April 29, 2016 13:22

doc: better example & synopsis

2595a7c

nodejs#6167 Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Robert Jefe Lindstädt <[email protected]>

doc: no Node.js(1)

3a4224d

Node.js(1) does not make sense. Node(1) would, but this isn’t a `man` page. nodejs#6167 Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Robert Jefe Lindstädt <[email protected]>

MylesBorins added the dont-land-on-v4.x label Jun 1, 2016

Fishrock123 added lts-watch-v4.x and removed dont-land-on-v4.x labels Jun 2, 2016

MylesBorins pushed a commit that referenced this pull request Jun 2, 2016

doc: better example & synopsis

a4888b0

PR-URL: #6167 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Robert Jefe Lindstädt <[email protected]>

MylesBorins pushed a commit that referenced this pull request Jun 2, 2016

doc: subdivide TOC, add auxiliary links

3001f88

PR-URL: #6167 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Robert Jefe Lindstädt <[email protected]>

MylesBorins added land-on-v4.x and removed lts-watch-v4.x labels Jun 2, 2016

MylesBorins pushed a commit that referenced this pull request Jun 2, 2016

doc: better example & synopsis

37daa32

PR-URL: #6167 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Robert Jefe Lindstädt <[email protected]>

MylesBorins pushed a commit that referenced this pull request Jun 2, 2016

doc: subdivide TOC, add auxiliary links

a87269d

PR-URL: #6167 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Robert Jefe Lindstädt <[email protected]>

MylesBorins mentioned this pull request Jun 24, 2016

v4.4.7 proposal #7395

Merged

MylesBorins pushed a commit that referenced this pull request Jun 24, 2016

doc: better example & synopsis

401325f

PR-URL: #6167 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Robert Jefe Lindstädt <[email protected]>

MylesBorins pushed a commit that referenced this pull request Jun 24, 2016

doc: subdivide TOC, add auxiliary links

eadb7e5

PR-URL: #6167 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Robert Jefe Lindstädt <[email protected]>

MylesBorins pushed a commit that referenced this pull request Jun 24, 2016

doc: better example & synopsis

d3c7b58

PR-URL: #6167 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Robert Jefe Lindstädt <[email protected]>

MylesBorins pushed a commit that referenced this pull request Jun 24, 2016

doc: subdivide TOC, add auxiliary links

3189446

PR-URL: #6167 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Robert Jefe Lindstädt <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: update synopsis, toc, other nits #6167

doc: update synopsis, toc, other nits #6167

Fishrock123 commented Apr 12, 2016 •

edited

Loading

jasnell commented Apr 12, 2016

Fishrock123 commented Apr 12, 2016

Fishrock123 commented Apr 12, 2016

Knighton910 commented Apr 12, 2016

benjamingr Apr 12, 2016

benjamingr commented Apr 12, 2016

trevnorris Apr 12, 2016

trevnorris Apr 12, 2016

Fishrock123 Apr 12, 2016

Fishrock123 commented Apr 15, 2016

Fishrock123 commented Apr 15, 2016

bengl Apr 15, 2016 •

edited

Loading

Fishrock123 commented Apr 27, 2016

Fishrock123 commented Apr 27, 2016

eljefedelrodeodeljefe Apr 27, 2016

eljefedelrodeodeljefe commented Apr 27, 2016

Fishrock123 commented Apr 27, 2016

eljefedelrodeodeljefe commented Apr 27, 2016

kahwee commented Apr 27, 2016

jasnell Apr 29, 2016

Fishrock123 Apr 29, 2016

jasnell Apr 29, 2016

Fishrock123 Apr 29, 2016

MylesBorins commented Jun 1, 2016

Fishrock123 commented Jun 2, 2016

MylesBorins commented Jun 2, 2016

doc: update synopsis, toc, other nits #6167

doc: update synopsis, toc, other nits #6167

Conversation

Fishrock123 commented Apr 12, 2016 • edited Loading

Checklist

Affected core subsystem(s)

Description of change

jasnell commented Apr 12, 2016

Fishrock123 commented Apr 12, 2016

Fishrock123 commented Apr 12, 2016

Knighton910 commented Apr 12, 2016

Choose a reason for hiding this comment

benjamingr commented Apr 12, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Fishrock123 commented Apr 15, 2016

Fishrock123 commented Apr 15, 2016

bengl Apr 15, 2016 • edited Loading

Choose a reason for hiding this comment

Fishrock123 commented Apr 27, 2016

Fishrock123 commented Apr 27, 2016

Choose a reason for hiding this comment

eljefedelrodeodeljefe commented Apr 27, 2016

Fishrock123 commented Apr 27, 2016

eljefedelrodeodeljefe commented Apr 27, 2016

kahwee commented Apr 27, 2016

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

MylesBorins commented Jun 1, 2016

Fishrock123 commented Jun 2, 2016

MylesBorins commented Jun 2, 2016

Fishrock123 commented Apr 12, 2016 •

edited

Loading

bengl Apr 15, 2016 •

edited

Loading