ROADMAP.md

Docs WG Roadmap

Jan 2016 → Apr 2016 (Q1)

This is the first of the quarterly roadmaps that this Working Group will produce, so it will be structured a bit differently than subsequent ones. Since this is a brand-new process, an explanation of what it is and why it's necessary follows.

This roadmap outlines the priorities for the Docs working group for the quarter. These tasks can be as broadly or narrowly defined as is useful. They are not necessarily staffed — as folks step up to do the work, we'll link tracking issues to the tasks for them to self-organize. Every quarter we'll revisit this roadmap, adding a quick postmortem of how things went, and creating a new set of priorities for the ensuing quarter.

That brings us to why a roadmap is necessary: the Node.js documentation is a relatively confined space to work within, and there are many interested parties: there are groups that consume the documentation as output, like the website working group, there are groups concerned with ensuring the content addresses the needs of diverse audiences, there are groups that are required to produce API documentation as a pre-requisite to merging their primary work, there are contributors who wish to help in a technical fashion, there are contributors who wish to contribute editorially, and there are the readers of the docs. All of these contributions overlap, so in order to make measurable progress without stepping on each other's feet, we have to:

• Set clear priorities — if two contributions conflict, it should be straightforward to determine which contribution should take precedence.
• Message these priorities well in advance — with this many stakeholders, we should mention repeatedly, loudly, and clearly what our intentions are. The Docs WG should aspire to avoid surprise.
• Make the best use of donated time — we want to ensure that if someone is donating their time to improve the documentation, it will be well-spent, and directed at driving the documentation towards this WG's stated goals.

Our goals can be summarized thusly:

Node.js should be in friendly competition for "Best Docs in OSS," with docs that address the needs of a wide variety of audiences — across skill levels, goals, and languages.

Tasks

Tasks for this quarter were drawn from responses to this issue. They are divided between three major areas:

• Content — the actual content of the docs
• Features — reader-focused features, like version metadata or autolinking.
• Tooling — author-focused features, like doc linting or html generation.

Since content is the ultimate product of this WG, it will usually be the highest priority. However, when content systemically fails audiences, it may point to a need for better features or tooling.

Right now, our features and tooling are lacking, and the content is suffering for it.

1️⃣ Pulling Guides into nodejs/node

This is our highest priority over the next two months.

Right now the documentation is split between the website repo and the core repo. We wish to bring the guide documentation into the core repo.

The existing node doctool is specifically built to only generate API docs. Until we can build the guide docs with Node.js' make doc command, guide documentation will be copied from the website repo into the core repo, but not removed from the website repo.

As a result, we are investigating using remark to build the docs. The stages of this project are as follows:

1. Use remark to build just the guides alongside the existing doctool.
2. Remove the guides from the website repository.
3. Identify and install the necessary remark plugins to faithfully render the API documentation.
4. Generate all documentation using remark. Fix lint issues pointed out by remark-lint.
5. Once no linting issues remain, wire up docs linting as part of Node.js' make test.

Once this project is complete, all doc style rules will be handled by remark, which includes line lengths, code samples (via eslint), markdown bullet and emphasis styles, and link checking. We will have a solid basis on which to add spelling and grammar checkers in the future, making it easier to maintain the docs going forward.

Subtasks

Want to pitch in? Look here! If someone's already working on the task, see if they need help.

• Identifying Remark plugins — @qard, others! nodejs/docs#61
• Initial Remark integration — @qard nodejs/node#4866
• Codify linting rules
  • Apply linting rules across API docs
• HTML layout for guide docs
• HTML layout update for API docs to include refs to guide docs

2️⃣ Guide and Topic Docs

A very close second to the work on the documentation tooling is the work on identifying and creating new guides and topic documentation. These two terms come up a lot, to clarify what they mean, here's an except from our getting started guide:

1. Guide documents explain processes to help the reader learn a concept in service of their larger goal. Usually a guide has the reader build something — a little webserver, or CLI — and explains the concept it's trying to convey using examples from the readers experience with that code. Guides are great for introducing new concepts in a comfortable way, by letting the reader "simulate" the process of what development will be like using those concepts.
2. Topic documents explain concepts to help the reader make a decision. They are a great place for "deep dive" information, and to handle anything that's fairly intricate.
3. Reference documents explain capabilities to help the reader achieve their goal. API documentation is the primary example of this.

Node.js currently has reference documentation, but because of the lack of topic and guide documentation, it ends up having to repeat itself a lot. Sometimes the lack of a dedicated place for this kind of documentation means that reference docs will attempt to include guides or topic docs inline — this usually doesn't end up working well in the long run.

The Docs WG has identified and created a few guides already, some of which are the subject of the first task. However, we need help filling in the gaps — both in identifying needed docs, as well as in executing on them.

It's important to note that this documentation applies as much to topics internal to the project as it does to our externally facing API — we need guides and overviews for the architecture of Node, as well as how to collaborate on the project.

Subtasks

Want to pitch in? Look here! If someone's already working on the task, see if they need help.

• Overviews:
  • "Encoding", to be used by the Buffer and FS docs.
  • "Blocking vs. non-blocking." — @jrit #77
  • Syscall documentation, to be used primarily by FS, but throughout the codebase.
  • Internal: Node.js Architecture — @eljefedelrodeodeljefe #71
  • Internal: Initialization process — @thealphanerd #73
  • Internal: Signals
  • Internal: Docs WG Process — @chrisdickinson
• Guides:
  • Internal: New Collaborator guide — @nodejs/inclusivity, @ashleygwilliams nodejs/inclusivity#96
  • Internal: Move "cutting releases" into these guides — @thealphanerd #75
  • Streams: For Authors
  • Streams: For Consumers — @bengl
  • Walkthroughs for each module
• Reference:
  • Glossary of terms, to be used by all docs.
  • Streams: remove guide content from API doc once guides have been written.
  • Streams: Descriptive spec — @nodejs/streams nodejs/readable-stream#181
• Identifying other docs to create

3️⃣ Improving API Metadata

One of the most common requests we've received is that the API docs start including relevant version information alongside methods. This information should include the version the API was introduced in, when it was last changed, and when it was deprecated, if applicable. Second to that, we've received requests to automatically link types of parameters to the appropriate MDN or Node.js documentation sections, and note what (if any) errors an API will generate, and how it will propagate them.

This points to the need to standardize tooling around this metadata, and then execute against that tooling.

This task should track the work being done in task #1 — that is to say, this metadata should be tracked by remark plugins in as much as is possible.

Subtasks

• Per-section YAML — @qard, @tflanagan nodejs/node#3867
• Noting 'version introduced' on each API — @tflanagan
  • Ideally this should link to the CHANGELOG for that release.
• Standardizing API method signature documentation
  • Type annotation — @fansworld-claudio nodejs/node#4741
    • (This will have to be brought into the Remark work as well.)
  • Error generation
• Automatically linking syscall(2)-format terms to the appropriate docs.
• Allow authors to pick a simpler anchor for headings in addition to the autogenerated anchor.

Notably Missing

There are a few things notably missing from this list — this is not because they are not important to us, but because we are primarily constrained by time and the size of the content we are working within. Foremost among the missing pieces is an internationalization strategy. This task cannot be approached lightly, and will likely include touching all of the docs in a single PR. While we welcome discussion on how to approach this issue, we will not be executing on it until after March 2016. Likewise, search is an extant issue that we do not have the resources to work on at present.

Pitching In

If you would like to help out with the Docs, you can:

• Find a subtask above and raise your hand on the associated issue or create an issue on the docs issue tracker.
• Raise your hand here to help with the weekly docs review load.