doc: update synopsis, toc, other nits#6167

Merged

Fishrock123 merged 3 commits intonodejs:masterfrom

Fishrock123:modernize-docs

Apr 29, 2016

Contributor

Fishrock123 commented Apr 12, 2016 •

edited

Loading

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

Fishrock123 added the doc label

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

Member

jasnell commented Apr 12, 2016

LGTM

Contributor Author

Fishrock123 commented Apr 12, 2016

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

Contributor Author

Fishrock123 commented Apr 12, 2016

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 commented Apr 12, 2016

👍

benjamingr reviewed

View reviewed changes

doc/api/_toc.markdown Outdated

Member

benjamingr Apr 12, 2016

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?

Member

benjamingr commented Apr 12, 2016

Two nits, generally LGTM

trevnorris reviewed

View reviewed changes

doc/template.html Outdated

Contributor

trevnorris Apr 12, 2016

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

Contributor

trevnorris Apr 12, 2016

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

Contributor Author

Fishrock123 Apr 12, 2016

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

Fishrock123 force-pushed the modernize-docs branch from e561107 to 2953a06 Compare

April 15, 2016 14:52

Contributor Author

Fishrock123 commented Apr 15, 2016

@benjamingr Updated, ptal.

@bengl have time to take a look?

Contributor Author

Fishrock123 commented Apr 15, 2016

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 reviewed

View reviewed changes

doc/api/synopsis.markdown Outdated

Member

bengl Apr 15, 2016 •

edited

Loading

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?

estliberitas force-pushed the master branch 2 times, most recently from 7da4fd4 to c7066fb Compare

April 26, 2016 05:23

Contributor Author

Fishrock123 commented Apr 27, 2016

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

Contributor Author

Fishrock123 commented Apr 27, 2016

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

Fishrock123 force-pushed the modernize-docs branch from 2953a06 to b70e5d6 Compare

April 27, 2016 16:30

eljefedelrodeodeljefe reviewed

View reviewed changes

doc/api/synopsis.md Outdated

Contributor

eljefedelrodeodeljefe Apr 27, 2016

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

Contributor

eljefedelrodeodeljefe commented Apr 27, 2016

LGTM w/ nits.

Fishrock123 force-pushed the modernize-docs branch from b70e5d6 to ec46ff1 Compare

April 27, 2016 21:32

Contributor Author

Fishrock123 commented Apr 27, 2016

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

Contributor

eljefedelrodeodeljefe commented Apr 27, 2016

👍 done deal then.

kahwee commented Apr 27, 2016

LGTM

jasnell reviewed

View reviewed changes

doc/api/synopsis.md Outdated

Member

jasnell Apr 29, 2016

nit: s/Node/Node.js

Contributor Author

Fishrock123 Apr 29, 2016

Maybe better as node example.js?

Member

jasnell Apr 29, 2016

that works too

Contributor Author

Fishrock123 Apr 29, 2016

Nvm, that's on the lines below

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 <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>


          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 <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>

MylesBorins added the dont-land-on-v4.x label

Contributor

MylesBorins commented Jun 1, 2016

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

Contributor Author

Fishrock123 commented Jun 2, 2016

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

Fishrock123 added lts-watch-v4.x and removed dont-land-on-v4.x labels

MylesBorins pushed a commit that referenced this pull request


          doc: better example & synopsis

a4888b0

PR-URL: #6167
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>

MylesBorins pushed a commit that referenced this pull request


          doc: no Node.js(1)

fb14bc9

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 <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>

MylesBorins pushed a commit that referenced this pull request


          doc: subdivide TOC, add auxiliary links

3001f88

PR-URL: #6167
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>

MylesBorins added land-on-v4.x and removed lts-watch-v4.x labels

Contributor

MylesBorins commented Jun 2, 2016

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

MylesBorins pushed a commit that referenced this pull request


          doc: better example & synopsis

37daa32

PR-URL: #6167
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>

MylesBorins pushed a commit that referenced this pull request


          doc: no Node.js(1)

124dfc1

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 <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>

MylesBorins pushed a commit that referenced this pull request


          doc: subdivide TOC, add auxiliary links

a87269d

PR-URL: #6167
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>

MylesBorins mentioned this pull request

v4.4.7 proposal #7395

Merged

MylesBorins pushed a commit that referenced this pull request


          doc: better example & synopsis

401325f

PR-URL: #6167
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>

MylesBorins pushed a commit that referenced this pull request


          doc: no Node.js(1)

107839c

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 <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>

MylesBorins pushed a commit that referenced this pull request


          doc: subdivide TOC, add auxiliary links

eadb7e5

PR-URL: #6167
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>

MylesBorins pushed a commit that referenced this pull request


          doc: better example & synopsis

d3c7b58

PR-URL: #6167
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>

MylesBorins pushed a commit that referenced this pull request


          doc: no Node.js(1)

f7068d4

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 <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>

MylesBorins pushed a commit that referenced this pull request


          doc: subdivide TOC, add auxiliary links

PR-URL: #6167
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

doc