Documentation Roadmap

[chrisdickinson]

Hi all —
I've noticed that it can be overwhelming to look at the state of the docs and try to pick a single thing out to work on. There are a ton of things that need improvement, and everyone sees different deficiencies in the docs. Further complicating matters, the docs are a relatively tight space to work within — it's really easy to end up stepping on other folks' toes when making larger changes.

With that in mind, I'd like to run a quick exercise. In this issue, I'd like you to list as many different features, tools, or docs that you think need work. At this point this is unranked listing — no +1's or votes at this point, please! Feel free to repeat items others have said, though. Examples might be:

• Doc tool needs to validate links
• Need internationalization strategy for node docs
• Create "guide" section
• Create glossary, define all jargon terms within
• Docs search
• Better docs on child process

I will close this issue at the end of the week and put forward a roadmap for discussion.

/cc @nodejs/documentation

[Qard]

• Migrate stuff from nodejs/nodejs.org over to nodejs/node
• Figure out what to do with the knowledge base content
• Lint code samples in docs?

Not sure if we should discuss the IA strategy again soon to decide how to handle the content migration. Might be a good idea.

[jrit]

User's that land on a page like this one https://github.com/nodejs/nodejs.org/blob/master/locale/en/docs/guides/simple-profiling.md which outputs to https://nodejs.org/en/docs/guides/simple-profiling/ can easily get confused about what version of node the doc is referring to. There is a PR open for the page here nodejs/nodejs.org#449 but there doesn't seem to be a good pattern here to refer to how this or other articles will describe how node works at different versions within the single document. In this case, for example, the tool referenced for 4.x is no longer in master and requires going into 4.2.4 on git to access here https://github.com/nodejs/node/tree/v4.2.4-proposal/tools/v8-prof

I realize this is somewhat specific to this article, but I think it illustrates the need to have more structure around this type of documentation staying correct for a range of versions.

@chrisdickinson thanks for all your dedication to the docs

[jasnell]

• providing clear, updated examples for each API
• providing basic, straightforward examples as early as possible in each
  document
  On Jan 18, 2016 7:41 PM, "Chris Dickinson" notifications@github.com wrote:

Hi all —
I've noticed that it can be overwhelming to look at the state of the docs
and try to pick a single thing out to work on. There are a ton of
things that need improvement, and everyone sees different deficiencies in
the docs. Further complicating matters, the docs are a relatively tight
space to work within — it's really easy to end up stepping on other folks'
toes when making larger changes.

With that in mind, I'd like to run a quick exercise. In this issue, I'd
like you to list as many different features, tools, or docs that you think
need work. At this point this is unranked listing — no +1's or votes at
this point, please! Feel free to repeat items others have said, though.
Examples might be:

• Doc tool needs to validate links
• Need internationalization strategy for node docs
• Create "guide" section
• Create glossary, define all jargon terms within
• Docs search
• Better docs on child process

I will close this issue at the end of the week and put forward a
roadmap for discussion.

/cc @nodejs/documentation
https://github.com/orgs/nodejs/teams/documentation

—
Reply to this email directly or view it on GitHub
#59.

[wraithan]

Documenting what things throw. Rust has it in their API docs like this: https://doc.rust-lang.org/std/string/struct.String.html#method.reserve

One case that has burned us at New Relic was process.memoryUsage which can throw an exception when file descriptors are exhausted. This is because (at least on linux) it opens a file to check the memory and just raises the exception. Theoretically it could throw under other situations too since it is a FS operation that just raises its errors.

[benjamingr]

I think it could be really nice to revamp the error messages errors have in Node.

I think doc pages should attempt to explain how to deal with said errors.

I'd like to discuss the possibility of comments on API methods like some other languages have.

[Qard]

Yeah...I really wish node had actual error codes and different error types. It really sucks having to parse the message to attempt to derive some actual context from the errors we get. It's kind of terrible. Better docs would help, but I think that's only part of the solution.

[DavidTPate]

• Documenting backwards compatible interfaces fs.writeFile(file, data[, options], callback) for example could be called with options as an encoding or an object with encoding. But this fact is not clear.
• Links between the documents. In fs.writeFile(file, data[, options], callback) for example encoding is mentioned many times but never linked to what encodings are supported and what they mean.
• Either links or expand docs for interfaces referenced externally. In FS for example there are many references to essentially man pages, but no links. So like chmod(2) could be replaced with a link or explanation of what chmod(2) means.

I think I've found where I want to focus on. I've done a lot of with FS and found many skeletons.

[evanlucas]

Linking in nodejs/node#1684

[giltayar]

1. For each API call, documenting from which version this API was available.

Yes, I know that I can go look at older versions of the API, but it's a pain. I would prefer always looking at the latest version and figuring out from there whether the API I want is available in that version or not.

1. For each API call, which errors are "thrown" from it.

[DavidTPate]

That a good point @giltayar

One of the documentation features I really liked from Android was that you could change you API Level (api version) and it would just grey out things that aren't supported on that version.

Check out this and change the API Level drop down and you'll see things change as you go. It also greys parts out on pages that weren't in that version.

[giltayar]

@DavidTPate - that's really really cool, and a lot of time must have been invested in that. But sometimes the simplest is the best in terms of value for effort: when adding an api, or changing it, just documenting the version number it was added/changed in. This will be for posterity, since the documentation is (I'm assuming) incremental.

Also, for me, doing it from this point onward is good enough. Again, in terms of value for effort, going back historically and figuring things out isn't worth the effort.

[Zirak]

The naming of anchors. For instance, the link to fs.symlink is fs.html#fs_fs_symlink_target_path_type_callback, which is both weird on the eye and impossible to type yourself if you're searching for a function's doc.

fs.html#symlink or even fs.html#fs.symlink are conceivable alternatives.

[ashleygwilliams]

hi! i'm from the @nodejs/inclusivity WG.

we fielded an issue about experiences joining large open source projects: nodejs/inclusivity#86

based on this, we plan on developing a Getting Started in Node.js tutorial that can serve as a friendly and approachable guide to open source contribution in Node. we hope to collect and organize a lot of the current work, as well as develop some new content, and eventually have it on nodejs.org

the tracking issue for this is here nodejs/inclusivity#96
(it's empty rn as we just approved it as a program in our meeting today)

would love to collaborate with ya'll

[Qard]

@Zirak That would break any existing links people have made to the docs from elsewhere. It may be possible to add extra anchors for cleaner names in the future doctool though. I'll add that to the list of stuff to consider.

@ashleygwilliams As I mentioned in that tracking issue, internals docs is a thing we want to be better at, which should help with that.

[Zirak]

@Qard You're right. A mediocre solution would be to just have both, something like:

<a [...] id="fs_fs_symlink_target_path_type_callback">#</a>
<a [...] id="symlink"></a>

[Fishrock123]

I know @ashleygwilliams has worked on for the npm docs, but we badly need something to clarify what unlink(2), and similar do. man page explanations, and links to a generalized posix doc or similar documentation on what specific things at very least generally do. This is a particularly bad problem in the fs docs.

[ashleygwilliams]

i have a module that converts 'unlink(3)' to a link. would love to make a PR. i was planning on it months ago and just forgot 😅

[shacharz]

Hi! Sorry if it already exists in the docs and I missed it.
I would love to see some higher level design and architecture documentation of nodejs.

Maybe some of it can link to v8 docs, but a whole picture that can get a beginner to wrap around his head about how exactly is nodejs built. All the way to the even loop, including design principles, and key optimization points.

An excellent example of this is Kafka's docs both the getting started and the design parts

[techjeffharris]

I'm imagining a target audience index similar to the API docs Stability index. Guides and Topics would have a target audience (beginner, intermediate, advanced) indicator at the top of the Topic/Guide possibly linking to prerequisite Guides and/or Topics.

We could provide a TOC Guide for each target audience--beginner, intermediate, and advanced--each of which could provide "pathways" to steer users to appropriate Topics based upon their skill levels. Granted, determining the skill level of a given Topic might be non-trivial.

I imagine API docs would almost always be advanced, as they are provided as a reference with boilerplate usage examples. A notice saying "This is Advanced stuff" especially if there are links to relevant Guides and Topics, would help direct users to Guides and Topics appropriate for their skill/knowledge level.

For example, a path for beginners:

• What is Node.js?
• Guide to using Docs
• Installation
• Hello World
• Globals
• Modules
• Events
• etc.

Intermediate:

• First HTTP server
• Intro to streams
• Debugger
• Net
• Child Process
• ES2015 Features

Advanced:

• Buffer
• Cluster
• Crypto
• TLS/SSL
• C/C++ Add-Ons
• VM

[eljefedelrodeodeljefe]

@techjeffharris Good list. I guess streams could be several times in all of these categories with varying topics. I'd imagine something curated like this piece of howtonode for it, that would explain streams not only as a class, but a powerful programming technique.

[techjeffharris]

Thanks! The list was from the top-of-my-head to get the ideas flowing. Great article, though it could be even better if kept up to date with latest changes and best practices.

[chrisdickinson]

OK, closing this now, slightly later than promised. What follows is a distillation of what's been mentioned in this issue, grouped into related chunks of work. This is not the roadmap itself, and it is not prioritized. I will propose a ROADMAP.md in a subsequent PR.

Content

• Identify common topics to pull into topic docs
  • Encoding — noted extensively in fs and buffer docs
  • Blocking vs. non-blocking calls.
  • Glossary for jargon terms
  • Syscalls
• Improve reference documentation
  • Provide useful examples for every API method
  • Remove non-reference material from reference docs
• Guides & Tutorials
  • Better error documentation, "how to deal with errors"
  • Provide walkthrough examples for each module
  • Adapt knowledge base content into new guides and tutorials
• Internal docs
  • Work with Diversity WG on contributor tutorial doc
  • High level architecture and design of node
  • Event loop, design principles, etc
  • Identify other docs to create

Metadata & Features for Readers

• Making sure guides and tutorials note pertinent version
• Add version information per API method (added, removed, changed)
• Internationalization strategy for docs
• Target audience index
• Document API signatures including what errors may be generated and how they're propagated
• Backwards compatibility in api signatures
• Docs search
• Automatically linking syscalls to syscall doc
• Automatically linking types in API signatures

Tooling (for authors)

• Improve anchor names (let authors pick an anchor name in addition to autogenerating it)
• lint code samples in docs
• turn docs WG guidelines into markdown linter rules
• migrate docs from nodejs/nodejs.org to nodejs/node
• New docs tool for guides (remark)
  • Migrate API docs off old doctool towards remark
• Document Docs WG process & execute on it

[chrisdickinson]

Oh, and I almost forgot to mention: Thank you all for participating in this!

[techjeffharris]

Great Distillation!