add initial version of guide #5

chrisdickinson · 2015-06-16T01:43:06Z

Adding an initial version of the guide to address #4.

The goal is to relate to documentation team members (and interested contributors) what we write about, how we write it, and why. This should serve as an initial style guide.

Feedback is greatly appreciated!

bengl · 2015-06-16T05:23:14Z

This is excellent! It addresses basically every meta-point I can remember coming up at the NodeConf docs sessions. Overall 👍, except for a few things:

Some of the lists aren't wrapped at 80 chars.
Should a particular flavour of Markdown be required? (i.e. GFM, etc.)
Since this includes some grammar rules, is US spelling preferred?
Might the last paragraph be expanded in the future (or sooner) to a full-on CONTRIBUTING.md/COLLABORATOR_GUIDE.md or maybe just use that of node? e.g. Is a green-button merge acceptable?

drewfish · 2015-06-16T05:42:19Z

GUIDE.md

+
+To summarize:
+
+* Structure is of paramount important.


Perhaps "importance"?

Good eye! Fixed in latest.

Qard · 2015-06-16T21:42:22Z

👍 I like the logical split into guides, topics and reference sections.

Other than the "importance" typo and needing to follow its own column-length requirements, it looks good to me.

chrisdickinson · 2015-06-16T22:26:00Z

OK, ready for another round of review.

chrisdickinson · 2015-06-16T22:35:20Z

/cc'ing @nodejs/diversity as well, since they might be interested!

chrisdickinson · 2015-06-16T22:36:05Z

GUIDE.md

+
+[as fun]: https://twitter.com/izs/status/187639633641865216
+[Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma
+[CONTRIBUTING.md]: CONTRIBUTING.md


I am working on the CONTRIBUTING.md guide in a separate PR so that we can incrementally approve changes.

That pull request is here.

Qard · 2015-06-16T22:45:20Z

LGTM

bengl · 2015-06-16T22:45:38Z

LGTM-too

distracteddev · 2015-06-16T23:05:46Z

GUIDE.md

+* US spelling is preferred. "Capitalize" vs. "Capitalise", "color" vs.
+  "colour", etc.
+* Though controversial, the [Oxford comma][] is preferred for clarity's sake.
+* Generally avoid personal pronouns in reference documentation ("I", "you",


We mention personal pronouns, did we want to make an explicit point regarding using non-gender specific pronounds?

Excellent point! Will fix.

distracteddev · 2015-06-16T23:06:49Z

Note: Did we want to link back to the overall node.js values once they are made public? I think we should make it explicit/clear that this is a strict subset of the values of the overall org and that those must be respected as well.

chrisdickinson · 2015-06-16T23:55:28Z

Note: Did we want to link back to the overall node.js values once they are made public? I think we should make it explicit/clear that this is a strict subset of the values of the overall org and that those must be respected as well.

Would it be okay to note this in the CONTRIBUTING guide? The values laid out in this document are scoped to the material and our relation to it: why we're writing it, where we put it, and how we write it. It seems like values (in the sense of project-wide values documenting the community and our relation to it) might fit more comfortably in CONTRIBUTING.md – which also has the nice side effect of being linked on all "create a PR" forms on GitHub.

As a separate concern – is GUIDE too generic a name for this doc? Maybe GETTING-STARTED? Or maybe this can be the README?

yorkie · 2015-06-17T01:03:30Z

Could we write some guidance for our markdown syntax limitation? Take an example:

We use the following syntax to define <code> block:

        var foo = 'this is a block'

over using the 3 characters "`":

```(start)
var foo = 'this is a block'
```(close)

The 2nd one is how we define a parameters of a function:
Similarly I think we have the following questions to ask:

how we define the function name and parameters
how we define the event format
how we make a correct link to another module or docs page
how the docs tool works locally so that patcher can review its change
etc.

If we let the docs newcomers know these more syntax rule, that would save time of reviewers.

BTW, just curious about why Node.js doesn't use any document generator tool like jsDoc or YUIDoc, that lets maintain the docs and codebase be easy.

jarofghosts · 2015-06-17T02:38:24Z

GUIDE.md

+
+* Our audiences are **diverse** and have **different goals** coming into the
+docs.
+* We write docs so that we our audiences can have a **positive experience** with


typo: "we our audiences"

Fixed – good eye!

chrisdickinson · 2015-06-17T02:39:19Z

@yorkie Noted re: codeblock usage. I haven't documented how we define function name + params yet. I might punt on it until a second revision.

BTW, just curious about why Node.js doesn't use any document generator tool like jsDoc or YUIDoc, that lets maintain the docs and codebase be easy.

Inline code documentation that is extracted via generators has to address two different audiences by its nature – both the programmer working on the code in-situ, as well as readers who are looking at the docs. It's hard to address both audiences in their current context well, so less is said. It ends up making serviceable reference documentation, but it doesn't address audiences looking for guides or topic material – and because it's inline in the code, it doesn't tend to link very well to those kinds of docs, either.

jarofghosts · 2015-06-17T02:42:09Z

GUIDE.md

+repeat that organization internally, so long as it does not interfere with the
+communication of the core idea of the document. For example, it's good to add
+links to reference materials at the end of topic docs, but it would be unwise
+to enumerate a modules entire list of methods inside that same doc. Another


typo: "modules" -> "module's"

yorkie · 2015-06-17T03:12:53Z

@chrisdickinson yes, I do agree on what you have described on audiences viewpoint, the problem in my previous PR experiences with Node.js is someone forget to update docs when he/she updated the codebase.

proposal: is there a possibility to introduce a scan tool to check if the "API" document is match to the current codebase 100%, and add the tool into CI system, then we can check if the PR does lost the related docs.

Trott · 2015-06-17T06:52:36Z

GUIDE.md

+# Node Documentation
+
+Welcome to the Node.js documentation guide – or more colloquially, the docs on
+docs. If you're here, you're likely looking for guidance on how to write


I like the engaging intro. There are some copyediting nits:

That looks like an en dash. It should be an em dash. (You can use HTML entities in markdown, so I'd recommend using the mdash entity here.)

No spaces before or after the dash.

"Node.js Documentation Guide" rather than "Node.js documentation guide"

If you think this will be read by many non-native speakers, you may be doing them a favor by avoiding words like colloquially.

That looks like an en dash. It should be an em dash. (You can use HTML entities in markdown, so I'd recommend using the mdash entity here.)

Willfix — it's easy enough to add a literal emdash here (— is Alt+Shift+hyphen on OSX.)

No spaces before or after the dash.

I'm following the NYT usage, where dashes are surrounded in spaces. Maybe I should note that in the mechanical section?

"Node.js Documentation Guide" rather than "Node.js documentation guide"

Willfix.

If you think this will be read by many non-native speakers, you may be doing them a favor by avoiding words like colloquially.

Oof, that is a good point. I had imagined that this doc would be translated by i18n teams, so the translation would only have to happen once. I wonder what the best way to survey non-native speakers is?

Ah! If you're using NY Times guide, I believe en dash rather than em dash is the way to go and (as you note) keep the spaces. So, basically, as you had it and ignore my dash comments.

And, yeah, whatever you use, noting the standard your using will help settle bike shed debates quickly. (And nothing brings out the bike shedding in everyone like copyediting. I'm doing it here!)

nebrius · 2015-06-17T18:43:14Z

Just a note from @nodejs/diversity, this is something we're definitely interested in, and would love to be involved with.

At this point in time, however, I wouldn't recommend waiting on us just yet. We're still very new, and I think it will be a while before we have anything finalized and public that can be cross referenced. Once everything is ready, we can circle back and look at collaborating/integrating/etc then.

Thanks for pinging us, and I like the direction this document is going in!

Fishrock123 · 2015-06-17T19:10:34Z

GUIDE.md

+      topics/streams/writing-a-stream.md    # for authors of streams
+      topics/streams/index.md               # links to both of the above
+
+In other cases, reference documentation may have need of describing a topic in


"may have to describe a topic" is probably easier to understand.

Fishrock123 · 2015-06-17T19:21:57Z

GUIDE.md

+  * Code need not be complete — treat code blocks as an illustration or aide to
+    your point, not as complete running programs. If a complete running program
+    is necessary, include it as an asset in `assets/code-examples` and link to
+    it.


I would like to add that any imported modules should either be shown, or the variables should be named as close as possible to those modules.

Another option is if the topic API was shown in an import as part of the high-level description.

Fishrock123 · 2015-06-17T19:25:21Z

Overall Looks good to me, minus comments.

I do suggest preferring markdown italics as _italics_, but it's mostly personal preference. (It does help distinguish from **bold**.)

Fishrock123 · 2015-06-17T20:56:43Z

GUIDE.md

+  * For illustrations, prefer SVG to other assets. When SVG is not feasible,
+    please keep a close eye on the filesize of the asset you're introducing.
+* For code blocks:
+  * Use language aware fences. ("```js")


Not sure this actually works, highlighting broke.

If you view the file it appears to render correctly.

chrisdickinson · 2015-06-18T02:11:29Z

Merging this now. Thanks all!

add initial version of guide

add initial version of guide

753d262

drewfish reviewed Jun 16, 2015
View reviewed changes

chrisdickinson mentioned this pull request Jun 16, 2015

Documentation Values #4

Closed

update guide

a7e0208

chrisdickinson reviewed Jun 16, 2015
View reviewed changes

distracteddev reviewed Jun 16, 2015
View reviewed changes

add note about gendered pronouns and mass nouns

6f29920

note code block usage, asset directory

db450c6

jarofghosts reviewed Jun 17, 2015
View reviewed changes

chrisdickinson added 2 commits June 16, 2015 20:02

spelling+grammar fixes

e23f60d

grammar fix

c9062dd

chrisdickinson added 2 commits June 16, 2015 22:23

fix code fence

3bc4414

link fixing.

69bf532

Trott reviewed Jun 17, 2015
View reviewed changes

chrisdickinson added 2 commits June 17, 2015 11:57

e{n -> m}dashes

cba12d9

capitalize guide title

3c79a3f

Fishrock123 reviewed Jun 17, 2015
View reviewed changes

update for latest feedback

d8d254e

Fishrock123 reviewed Jun 17, 2015
View reviewed changes

more notes

8edf65b

TIL grammar edition

be3a959

Fishrock123 reviewed Jun 17, 2015
View reviewed changes

rename GUIDE -> GETTING-STARTED

a4c0ab8

chrisdickinson added a commit that referenced this pull request Jun 18, 2015

Merge pull request #5 from chrisdickinson/master

d521df3

add initial version of guide

chrisdickinson merged commit d521df3 into nodejs:master Jun 18, 2015

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add initial version of guide #5

add initial version of guide #5

chrisdickinson commented Jun 16, 2015

bengl commented Jun 16, 2015

drewfish Jun 16, 2015

chrisdickinson Jun 16, 2015

Qard commented Jun 16, 2015

chrisdickinson commented Jun 16, 2015

chrisdickinson commented Jun 16, 2015

chrisdickinson Jun 16, 2015

chrisdickinson Jun 17, 2015

Qard commented Jun 16, 2015

bengl commented Jun 16, 2015

distracteddev Jun 16, 2015

chrisdickinson Jun 16, 2015

chrisdickinson Jun 16, 2015

distracteddev commented Jun 16, 2015

chrisdickinson commented Jun 16, 2015

yorkie commented Jun 17, 2015

jarofghosts Jun 17, 2015

chrisdickinson Jun 17, 2015

chrisdickinson commented Jun 17, 2015

jarofghosts Jun 17, 2015

chrisdickinson Jun 17, 2015

yorkie commented Jun 17, 2015

Trott Jun 17, 2015

chrisdickinson Jun 17, 2015

Trott Jun 17, 2015

nebrius commented Jun 17, 2015

Fishrock123 Jun 17, 2015

chrisdickinson Jun 17, 2015

Fishrock123 Jun 17, 2015

Fishrock123 commented Jun 17, 2015

Fishrock123 Jun 17, 2015

chrisdickinson Jun 17, 2015

chrisdickinson commented Jun 18, 2015

add initial version of guide #5

add initial version of guide #5

Conversation

chrisdickinson commented Jun 16, 2015

bengl commented Jun 16, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Qard commented Jun 16, 2015

chrisdickinson commented Jun 16, 2015

chrisdickinson commented Jun 16, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Qard commented Jun 16, 2015

bengl commented Jun 16, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

distracteddev commented Jun 16, 2015

chrisdickinson commented Jun 16, 2015

yorkie commented Jun 17, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrisdickinson commented Jun 17, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yorkie commented Jun 17, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nebrius commented Jun 17, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Fishrock123 commented Jun 17, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrisdickinson commented Jun 18, 2015