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.