Docs WG Ratification

[chrisdickinson]

There's been a bunch of discussion with regards to getting ratified on the Node tracker.

The current proposal is:

• All of our docs live within the Node repo.
  • Commit cleanliness would be relaxed for authors — the person merging will clean up those commits.
• This repo exists for coordination and (possibly) review of net new docs before merging into Node.
• The docs team has jurisdiction over doc/, tools/docs; and shares responsibility for doc/api with the core team.
• Before ratification, we do a call for membership to make sure we're including contributors that we missed over the last months.
  • Once we are ratified, we can then suggest the proposed IA changes as PRs to the main repo.
    • This might be as simple as PR'ing the knowledge base & tutorials we've written up until this point into the Node repo for discussion.

While I've been in contact with a few of us, I'd like to make sure we're OK with this plan going forward.

/cc @nodejs/documentation

[Qard]

👍 from me. 😸

[rvagg]

It seems to me that one of the major blockers is the "shares responsibility for doc/api with the core team" bit; where core wants to have API docs tied closely to API so new PRs affecting API can have "update the docs too" enforced in the same way as "add a test" is enforced. With the docs living elsewhere or being managed by a separate group this becomes more cumbersome and may impact the pace of progress.

So, perhaps its worth exploring the idea of using tooling to solve the conflict. e.g. the API docs that core owns are purely descriptive and have a well defined format. Perhaps its even JSON or semi-JSON, with fields such as "arguments", "errors", "return value", maybe going so far as to include a basic description but stopping short of being complete. Then tooling could be used to generate the final docs by pulling in this formal data and combining it with data owned by the docs group that fleshes out the formal descriptives with expanded descriptions, examples, warnings, links to tutorials, etc. A case could be made here that what core needs to own is very limited in scope and it would be healthier for the docs as a whole for that scope to be well defined so that we can allow for clearer distinction between contributing code and contributing docs when it comes to core's API docs (great coders are rarely great documenters and vice versa so how about we make our processes allow for that?). At a minimum, having a non-freeform API doc specification format would help with consistency, we keep on making note of how inconsistent it all is (e.g. nodejs/node#4362 (comment)). /cc @jasnell

[jasnell]

I definitely like the idea of separating this out and having a more machine
readable root format for the API docs so long as there is solid effort
going into refining those into polished rich documentation. I can even take
a stab at writing up an initial version.
On Jan 8, 2016 5:18 AM, "Rod Vagg" notifications@github.com wrote:

It seems to me that one of the major blockers is the "shares
responsibility for doc/api with the core team" bit; where core wants to
have API docs tied closely to API so new PRs affecting API can have "update
the docs too" enforced in the same way as "add a test" is enforced. With
the docs living elsewhere or being managed by a separate group this becomes
more cumbersome and may impact the pace of progress.

So, perhaps its worth exploring the idea of using tooling to solve the
conflict. e.g. the API docs that core owns are purely descriptive and
have a well defined format. Perhaps its even JSON or semi-JSON, with fields
such as "arguments", "errors", "return value", maybe going so far as to
include a basic description but stopping short of being complete. Then
tooling could be used to generate the final docs by pulling in this formal
data and combining it with data owned by the docs group that fleshes out
the formal descriptives with expanded descriptions, examples, warnings,
links to tutorials, etc. A case could be made here that what core needs to
own is very limited in scope and it would be healthier for the docs as a
whole for that scope to be well defined so that we can allow for clearer
distinction between contributing code and contributing docs when it comes
to core's API docs (great coders are rarely great documenters and vice
versa so how about we make our p rocesses allow for that?). At a minimum,
having a non-freeform API doc specification format would help with
consistency, we keep on making note of how inconsistent it all is (e.g. nodejs/node#4362
(comment)
nodejs/node#4362 (comment)). /cc
@jasnell https://github.com/jasnell

—
Reply to this email directly or view it on GitHub
#50 (comment).

[Qard]

I think just pulling all the non-reference content out into guides is probably enough. Code PRs would have to include reference docs, but in-depth guides could be written separately.

[chrisdickinson]

@jasnell, @rvagg: This is an interesting approach! However, I'd like to avoid new tooling until we:

1. Figure out membership,
2. Have a meeting to discuss direction,
3. And become ratified.

Which isn't to say we can't have a discussion around doc tooling (which I agree, needs to improve!), but that we shouldn't focus on doc tooling as a key piece of getting the WG stood up.

Process discussion is totally viable at this stage, though, especially in terms of reducing friction between core and the Docs WG. Perhaps the Docs WG doesn't block code PRs for doc review, but instead has a weekly task of editing newly merged documentation — the only thing the WG could block would be releases, in order to make sure the docs are in a good state?

[chrisdickinson]

We're ratified!

[eljefedelrodeodeljefe]

very goood!