From ee1b7bef25c16bffd346497c98e4c13616765ded Mon Sep 17 00:00:00 2001 From: Chris Dickinson Date: Wed, 27 Jan 2016 19:32:21 -0800 Subject: [PATCH 1/7] add first draft of ROADMAP.md --- ROADMAP.md | 227 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 227 insertions(+) create mode 100644 ROADMAP.md diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..a8f067a --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,227 @@ +# 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][wg-website], there are groups concerned with ensuring +the [content addresses the needs of diverse audiences][wg-diversity], there are +[groups that are required][wg-ctc] 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][goals]. + +[Our goals][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][issue-roadmap]. +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.** + +#### :one: Pulling Guides into [nodejs/node][repo-nodejs] + +**This is our highest priority over the next two months.** + +Right now the documentation is split between the [website repo][wg-website] and +the [core repo][wg-ctc]. We wish to bring the [guide documentation][guide-docs] +into the core repo. + +The existing [node doctool][ref-doctool] is specifically built to _only_ +generate API docs. Until we can build the guide docs with Node's `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][ref-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's + `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](https://github.com/nodejs/docs/issues/61) +* Initial Remark integration — **@qard** [nodejs/node#4866](https://github.com/nodejs/node/pull/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 + +#### :two: 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][ref-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 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](#one-pulling-guides-into-nodejsnode) 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." + * Syscall documentation, to be used primarily by FS, but throughout the codebase. + * Internal: Node Architecture + * Internal: Initialization process + * Internal: Timers + * Internal: Event loop + * Internal: Signals + * Internal: Docs WG Process — **@chrisdickinson** +* Guides: + * Internal: New Collaborator guide — **@nodejs/diversity**, **@ashleygwilliams** [nodejs/diversity#96](https://github.com/nodejs/inclusivity/issues/96) + * Internal: Move "cutting releases" into these guides. + * Streams: For Authors + * Streams: For Consumers + * 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](https://github.com/nodejs/readable-stream/issues/181) +* Identifying other docs to create + +#### :three: 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 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](https://github.com/nodejs/node/pull/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](https://github.com/nodejs/node/pull/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][docs-tracker]. +* Raise your hand [here][weekly-review] to help with the weekly docs review + load. + +[goals]: https://github.com/nodejs/node/blob/master/WORKING_GROUPS.md#documentation +[wg-website]: https://github.com/nodejs/diversity +[issue-roadmap]: https://github.com/nodejs/docs/issues/59 +[repo-nodejs]: https://github.com/nodejs/node +[wg-website]: https://github.com/nodejs/nodejs.org/ +[wg-diversity]: https://github.com/nodejs/diversity/ +[wg-ctc]: https://github.com/nodejs/node +[guide-docs]: https://github.com/nodejs/nodejs.org/tree/master/locale/en/docs/guides +[ref-doctool]: https://github.com/nodejs/node/tree/master/tools/doc +[ref-remark]: https://www.npmjs.com/package/remark +[ref-getting-started]: ./GETTING-STARTED.md +[docs-tracker]: https://github.com/nodejs/docs/issues/new +[weekly-review]: https://github.com/nodejs/docs/issues/69 From f0e7ed507b756b6c8b241eb8b89bc02ff89f1b57 Mon Sep 17 00:00:00 2001 From: Chris Dickinson Date: Wed, 27 Jan 2016 19:35:28 -0800 Subject: [PATCH 2/7] s/diversity/inclusivity/g --- ROADMAP.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index a8f067a..2c10d3b 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -18,7 +18,7 @@ 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][wg-website], there are groups concerned with ensuring -the [content addresses the needs of diverse audiences][wg-diversity], there are +the [content addresses the needs of diverse audiences][wg-inclusivity], there are [groups that are required][wg-ctc] 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 @@ -152,7 +152,7 @@ if they need help. * Internal: Signals * Internal: Docs WG Process — **@chrisdickinson** * Guides: - * Internal: New Collaborator guide — **@nodejs/diversity**, **@ashleygwilliams** [nodejs/diversity#96](https://github.com/nodejs/inclusivity/issues/96) + * Internal: New Collaborator guide — **@nodejs/inclusivity**, **@ashleygwilliams** [nodejs/inclusivity#96](https://github.com/nodejs/inclusivity/issues/96) * Internal: Move "cutting releases" into these guides. * Streams: For Authors * Streams: For Consumers @@ -213,11 +213,11 @@ If you would like to help out with the Docs, you can: load. [goals]: https://github.com/nodejs/node/blob/master/WORKING_GROUPS.md#documentation -[wg-website]: https://github.com/nodejs/diversity +[wg-website]: https://github.com/nodejs/inclusivity [issue-roadmap]: https://github.com/nodejs/docs/issues/59 [repo-nodejs]: https://github.com/nodejs/node [wg-website]: https://github.com/nodejs/nodejs.org/ -[wg-diversity]: https://github.com/nodejs/diversity/ +[wg-inclusivity]: https://github.com/nodejs/inclusivity/ [wg-ctc]: https://github.com/nodejs/node [guide-docs]: https://github.com/nodejs/nodejs.org/tree/master/locale/en/docs/guides [ref-doctool]: https://github.com/nodejs/node/tree/master/tools/doc From a6deb5df8101b30f15f9a006361e61589f121d2a Mon Sep 17 00:00:00 2001 From: Chris Dickinson Date: Wed, 27 Jan 2016 20:13:11 -0800 Subject: [PATCH 3/7] remove bad link --- ROADMAP.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index 2c10d3b..66e5e8d 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -212,16 +212,15 @@ If you would like to help out with the Docs, you can: * Raise your hand [here][weekly-review] to help with the weekly docs review load. +[docs-tracker]: https://github.com/nodejs/docs/issues/new [goals]: https://github.com/nodejs/node/blob/master/WORKING_GROUPS.md#documentation -[wg-website]: https://github.com/nodejs/inclusivity -[issue-roadmap]: https://github.com/nodejs/docs/issues/59 -[repo-nodejs]: https://github.com/nodejs/node -[wg-website]: https://github.com/nodejs/nodejs.org/ -[wg-inclusivity]: https://github.com/nodejs/inclusivity/ -[wg-ctc]: https://github.com/nodejs/node [guide-docs]: https://github.com/nodejs/nodejs.org/tree/master/locale/en/docs/guides +[issue-roadmap]: https://github.com/nodejs/docs/issues/59 [ref-doctool]: https://github.com/nodejs/node/tree/master/tools/doc -[ref-remark]: https://www.npmjs.com/package/remark [ref-getting-started]: ./GETTING-STARTED.md -[docs-tracker]: https://github.com/nodejs/docs/issues/new +[ref-remark]: https://www.npmjs.com/package/remark +[repo-nodejs]: https://github.com/nodejs/node [weekly-review]: https://github.com/nodejs/docs/issues/69 +[wg-ctc]: https://github.com/nodejs/node +[wg-inclusivity]: https://github.com/nodejs/inclusivity/ +[wg-website]: https://github.com/nodejs/nodejs.org/ From db18343fae807d304209fc360b8b853312f5ea5f Mon Sep 17 00:00:00 2001 From: Chris Dickinson Date: Thu, 28 Jan 2016 11:59:00 -0800 Subject: [PATCH 4/7] standardize on "Node.js" --- ROADMAP.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index 66e5e8d..e0595d9 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -37,7 +37,7 @@ on each other's feet, we have to: [Our goals][goals] can be summarized thusly: -> Node.JS should be in friendly competition for "Best Docs in OSS," with docs +> 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. @@ -66,7 +66,7 @@ the [core repo][wg-ctc]. We wish to bring the [guide documentation][guide-docs] into the core repo. The existing [node doctool][ref-doctool] is specifically built to _only_ -generate API docs. Until we can build the guide docs with Node's `make doc` +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. @@ -79,7 +79,7 @@ docs. The stages of this project are as follows: 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's +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, @@ -120,7 +120,7 @@ started][ref-getting-started] guide: > 3. **Reference** documents explain capabilities to help the reader achieve > their goal. API documentation is the primary example of this. -Node currently has **reference** documentation, but because of the lack of +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 — @@ -145,7 +145,7 @@ if they need help. * "Encoding", to be used by the Buffer and FS docs. * "Blocking vs. non-blocking." * Syscall documentation, to be used primarily by FS, but throughout the codebase. - * Internal: Node Architecture + * Internal: Node.js Architecture * Internal: Initialization process * Internal: Timers * Internal: Event loop @@ -170,7 +170,7 @@ 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 documentation sections, and note what (if any) errors an API will +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 From d7175c6107da211bba8b1bf77e6aeeb11c821af1 Mon Sep 17 00:00:00 2001 From: Chris Dickinson Date: Fri, 29 Jan 2016 13:12:05 -0800 Subject: [PATCH 5/7] note that eljefedelrodeodeljefe is working on the architecture guide --- ROADMAP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ROADMAP.md b/ROADMAP.md index e0595d9..10c3d53 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -145,7 +145,7 @@ if they need help. * "Encoding", to be used by the Buffer and FS docs. * "Blocking vs. non-blocking." * Syscall documentation, to be used primarily by FS, but throughout the codebase. - * Internal: Node.js Architecture + * Internal: Node.js Architecture — **@eljefedelrodeodeljefe** [#71](https://github.com/nodejs/docs/issues/71) * Internal: Initialization process * Internal: Timers * Internal: Event loop From b57f3e20c1df155c3ca07a3afd9b1059d2abce97 Mon Sep 17 00:00:00 2001 From: Chris Dickinson Date: Wed, 3 Feb 2016 11:57:20 -0800 Subject: [PATCH 6/7] add folks who have their hands up! --- ROADMAP.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index 10c3d53..fde9622 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -146,16 +146,16 @@ if they need help. * "Blocking vs. non-blocking." * Syscall documentation, to be used primarily by FS, but throughout the codebase. * Internal: Node.js Architecture — **@eljefedelrodeodeljefe** [#71](https://github.com/nodejs/docs/issues/71) - * Internal: Initialization process + * Internal: Initialization process — **@thealphanerd** * Internal: Timers - * Internal: Event loop + * Internal: Event loop — **@DavidTPate** * Internal: Signals * Internal: Docs WG Process — **@chrisdickinson** * Guides: * Internal: New Collaborator guide — **@nodejs/inclusivity**, **@ashleygwilliams** [nodejs/inclusivity#96](https://github.com/nodejs/inclusivity/issues/96) - * Internal: Move "cutting releases" into these guides. + * Internal: Move "cutting releases" into these guides — **@thealphanerd** * Streams: For Authors - * Streams: For Consumers + * Streams: For Consumers — **@bengl** * Walkthroughs for each module * Reference: * Glossary of terms, to be used by all docs. From b8a90e430cbd3ac4a565512da48c39b36fb63c57 Mon Sep 17 00:00:00 2001 From: Chris Dickinson Date: Wed, 3 Feb 2016 15:27:43 -0800 Subject: [PATCH 7/7] add tracking issues --- ROADMAP.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index fde9622..b7be3eb 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -146,14 +146,14 @@ if they need help. * "Blocking vs. non-blocking." * Syscall documentation, to be used primarily by FS, but throughout the codebase. * Internal: Node.js Architecture — **@eljefedelrodeodeljefe** [#71](https://github.com/nodejs/docs/issues/71) - * Internal: Initialization process — **@thealphanerd** + * Internal: Initialization process — **@thealphanerd** [#73](https://github.com/nodejs/docs/issues/73) * Internal: Timers - * Internal: Event loop — **@DavidTPate** + * Internal: Event loop — **@DavidTPate** [#74](https://github.com/nodejs/docs/issues/74) * Internal: Signals * Internal: Docs WG Process — **@chrisdickinson** * Guides: * Internal: New Collaborator guide — **@nodejs/inclusivity**, **@ashleygwilliams** [nodejs/inclusivity#96](https://github.com/nodejs/inclusivity/issues/96) - * Internal: Move "cutting releases" into these guides — **@thealphanerd** + * Internal: Move "cutting releases" into these guides — **@thealphanerd** [#75](https://github.com/nodejs/docs/issues/75) * Streams: For Authors * Streams: For Consumers — **@bengl** * Walkthroughs for each module