doc: add Docs working group

[bengl]

Proposed charter for Documentation working group.

[jasnell]

s/aintaining/maintaining

[bengl]

whoops! (although aintaining sounds funny) will fix.

[jasnell]

Couple nits but LGTM

[bengl]

@jasnell cool. nits addressed.

[jasnell]

@nodejs/ctc

[chrisdickinson]

Would "content structure" fall under style?

[bengl]

I'd think so. I'll add it in to clarify.

[bengl]

changed in latest push.

[jasnell]

additional changes still LGTM :-)

[rvagg]

I'm a little hesitant to support this because from what I can tell the docs group so far hasn't been able to live up to the initial hopes that many of us had, most likely due to the time constraints on individuals involved. I could be missing activity but my personal preference is to not have too many inactive WGs in our list. The current trajectory makes it seem that this group is likely to end up in a similar place to the Streams WG.

Perhaps we need a short summary of the kind of activity this group has under its belt so far and the kind of responsibility it can reasonably expect to be able to take on given data we have on the individuals able to spend time on this? It'd also be good to hear about group leadership/facilitatorship, are there individuals able to take on roles in keeping this group active and make sure it doesn't completely fizzle out?

If we had a proper incubation process for working groups where they had to meet certain viability metrics, would the Docs WG make it through?

[jasnell]

An incubation period for WGs would be good. But also keep in mind that we
also have the option of un-chartering WGs as necessary
On Dec 13, 2015 7:05 PM, "Rod Vagg" notifications@github.com wrote:

I'm a little hesitant to support this because from what I can tell the
docs group so far hasn't been able to live up to the initial hopes that
many of us had, most likely due to the time constraints on individuals
involved. I could be missing activity but my personal preference is to not
have too many inactive WGs in our list. The current trajectory makes it
seem that this group is likely to end up in a similar place to the Streams
WG.

Perhaps we need a short summary of the kind of activity this group has
under its belt so far and the kind of responsibility it can reasonably
expect to be able to take on given data we have on the individuals able to
spend time on this? It'd also be good to hear about group
leadership/facilitatorship, are there individuals able to take on roles in
keeping this group active and make sure it doesn't completely fizzle out?

If we had a proper incubation process for working groups where they had to
meet certain viability metrics, would the Docs WG make it through?

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

[tflanagan]

There are definitely goals for future docs that should be laid out, would help put this WG on a roadmap.

One such item is the "since version" proposal.

Docs are just as important as good core code, and should be treated as such, without good and easy to use docs, projects can wither, things get confusing, etc.

+1 having a WG

[orangemocha]

Changes LGTM

Regarding @rvagg 's concerns, perhaps we could have a periodic review of working groups and their activities? We'll probably want to address different causes of inactivity differently, for example:

• a group that has accomplished most of its objectives and is now dormant could just moved to an 'archived' state.
• a group that hasn't taken off because its model was somehow flawed could be un-chartered
• for a group that we believe has a valid purpose but not enough traction, we could think of ways to promote it.

Not sure what happened to the Streams WG but in case of a Docs WG we should probably think of ways to ignite it its activities. It certainly sounds like a good WG for new collaborators to get involved.

[rvagg]

@tflanagan having a WG doesn't guarantee things getting done, it could be the opposite in fact. If there's nobody with enough time to dedicate to the WG but core collaborators believe that documentation concerns can be delegated to that WG, the work may end up not being done at all.

[bengl]

@rvagg Here's a rough stab at answering your questions:

Brief summary of group's activity: In terms of productivity in the existing group, yes, there was an initial flurry of activity in the existing group including the establishment of a docs style guide and other intro-to-docs docs, along with several long-form guides which have been since been moved over to the website repo. Since then, there have been quite a few commits to API docs both from folks in @nodejs/documentation and outside of that team. Members who are also collaborators on core have also been in the review process for PRs involving documentation. So, yes, while this isn't a huge amount activity, and the docs repo hasn't been particularly active, there have been some things going on.

In terms of leadership/facilitatorship, @chrisdickinson has largely taken up that role. He's currently listed as an owner on the repo (I'm not entirely sure how repo ownership works within Github orgs ¯_ツ_/¯ ). I've also taken a bit of a role in organizing the first docs meeting, and am happy to step up if needed (and am able, time-wise).

Also I'm super-interested in what an incubation process might entail. I want to see a successful Docs WG, so if there are measurable criteria to aim for, that's quite helpful and awesome.

[Qard]

I'm one of those folks in the docs wg with constrained time. I think the docs stuff is really important, but we really need more people to get involved.

A working group being unable to achieve as much as is hoped is probably not an indicator that it doesn't work or shouldn't exist so much as that it needs more resources. There's only a handful of us, we need help and we're not going to get it if we get swept under the carpet.

[rvagg]

@chrisdickinson how's are you currently positioned to be a facilitator of this group? My impression is that things have become very busy for you since your move to npm. Would we best to explicitly encourage @bengl to take a lead role here in making it all happen?

[chrisdickinson]

@rvagg I'd be ok with @bengl taking a lead role on facilitating the group. Once my schedule frees up I can take over more facilitating duties, if that helps.

[MylesBorins]

Have there been many situations where a decision based on docs requires escalation to committee? I have not been around that long, but most things seem to be moving forward pretty quickly.

It seems like what may be blocking docs moving at a better pace is a lack of collaborators with the time and motivation to focus on documentation.

Perhaps we should consider bringing collaborators into the project who are doc focused

[chrisdickinson]

Have there been many situations where a decision based on docs requires escalation to committee?

The Docs WG is unlike the TC/CTC/TSC — it's not a destination for issues to be escalated to. It exists to address the problem building a team and process around the docs that can:

1. Maintain consistent voice in the docs,
2. Address structural issues in the docs,
3. and ensure that we're serving all of the audiences that are coming to our docs for answers.

The system we have in place produces documentation that does not meet these goals, hence the desire to form a WG to address the problem. It's important to note that the WG doesn't exist to supplant the efforts of individual collaborators, but to focus those efforts towards building better docs.

[indexzero]

I am a mega +1 on this. @rvagg I am a bit surprised by your response since the topic of focusing on increased adoption in 2016 was so positively supported by the entire board, including yourself.

I strongly feel there should be a chartered WG because only then does this topic have the official capacity to request the budget it needs to be where we all want it to be.

I have to 100% confidence in @bengl as coordinator, but I speak specifically of budget because writing a lot of technical documentation with a cohesive voice is very hard.

We worked with @mikeal to include the content for docs.nodejitsu.com and will likely officially donate it if there is interest as a way to kick start this effort.

As old and outdated as those are that site still gets A LOT of traffic. Traffic that has no where to go if that site went away. A chartered docs WG could make that and many other awesome secondary documentation efforts around guides, tutorials and how tos a reality for new folks to node.

[jasnell]

Charlie, I don't believe it's a reluctance to see the work move forward but
a concern over chartering WGs that don't seem to make progress.
On Dec 18, 2015 1:10 PM, "Charlie Robbins" notifications@github.com wrote:

I am a mega +1 on this. @rvagg https://github.com/rvagg I am a bit
surprised by your response since the topic of focusing on increased
adoption in 2016 was so positively supported by the entire board, including
yourself.

I strongly feel there should be a chartered WG because only then does this
topic have the official capacity to request the budget it needs to be where
we all want it to be.

I have to 100% confidence in @bengl https://github.com/bengl as
coordinator, but I speak specifically of budget because writing a lot of
technical documentation with a cohesive voice is very hard.

We worked with @mikeal https://github.com/mikeal to include the content
for docs.nodejitsu.com and will likely officially donate it if there is
interest as a way to kick start this effort.

As old and outdated as those are that site still gets A LOT of traffic.
Traffic that has no where to go if that site went away. A chartered docs WG
could make that and many other awesome secondary documentation efforts
around guides, tutorials and how tos a reality for new folks to node.

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

[indexzero]

Talking about these things in the abstract is not helpful. For example: on average everyone has been dead for 100 years.

I would like us instead to focus on concrete requirements:

• About half the people using node have been doing so for less than a year.
• The API docs are fine reference material, but lack initial context for new folks.

The foundation is doing budget reforecasting now and the January board meeting will discuss how to use it. If there was ever a time for CTC or other WG folks to submit a proposal about how a part-time contractor or a fixed price contract could push forward their charter now is the time to do it.

The problem for docs is that there isn't even a group dedicated to talking about it officially. So how would this topic get to the board otherwise?

[mikeal]

I think this is one of those cases where we don't have a shared understanding of the state this is all in or the goals we'd like to reach.

Some background, there are currently 3 completely disconnected efforts you would call "documentation":

• Docs on the website
  • Some of these are in the "knowledge base" which was kickstarted by old nodejitsu docs.
  • Some of these are docs that were migrated from the initial website
  • Some of these are new docs, a few of which originated in the docs repo the "Docs WG" setup.
• Documentation Working Group: An experiment around new tools and processes for creating documentation.
  • Some of the actual content that was produced made its way to the website and basically lives there now.
  • Most of the complaints people seem to have about "not living up to our hopes" or whatever are due to the fact that this effort seemed to be blocked by the development of tools that were never finished AFAIK.
• API Documentation
  • Judging by the commit history there's a pretty active community making improvements to this without any real acknowledgment as a WG or team.
  • There's probably some work we could do here to loosen the regular contribution process for doc changes and just have contributors doing the merge fix issues like commit metadata. @thealphanerd and I were just talking about this at lunch.

Ok, so we have three buckets of work being done. As it stands I don't see a compelling reason to merge them all together. In fact, I'm a little concerned that we have a "docs" repo and "Docs WG" when there are so may people doing docs work that isn't included in that.

My recommendation would be:

• Create a new "knowledge-base" team that has write access to the website and drive an effort there to clean up the existing docs, organize them better, and write new material.
• Create a new "api-docs" team which is a subset of the existing committers on core who are maintaining the docs and pull them in to doc issues similarly to what we do with the crypto team.
• I have no idea what to do about the docs repo/tools effort, I haven't been following it much recently but if it's in the state it was a few months ago I think that we would be better off focusing efforts where content is being created and maintained and build up tools and process around it rather than the greenfield approach that WG has taken.

[bengl]

Judging by the commit history there's a pretty active community making improvements to this without any real acknowledgment as a WG or team.

IIRC at least a few docs commits have gotten @nodejs/documentation summoned, followed by members of that team who happen to be collaborators providing some review. This is what I would hope a large portion of involvement would be going forward (as with other teams and their areas of focus). Also, I would expect that as the WG ramps up, those putting a lot of work into docs would be invited to join as well.

As it stands I don't see a compelling reason to merge them all together.

A bit of unity on documentation would be nice. As @chrisdickinson and others mentioned, there are some issues in the current sets of documentation that need resolving and having the centralized structure for identifying the issues and coordinating their resolution (across repos, where appropriate) would be pretty helpful.

In fact, I'm a little concerned that we have a "docs" repo and "Docs WG" when there are so may people doing docs work that isn't included in that.

I'm not entirely sure that this is a problem? I don't think the team, repo or "WG" would have any intention or goal to block people from contributing, but instead to foster, enable, and guide that kind of activity. I'd say more communication and visibility is needed. Also, action. I'd hope that chartering the group would help at least a little bit with that.

[chrisdickinson]

The intent was never to take a greenfield approach. I approached the Node project suggesting that we move the docs into a repo where the docs team could implement a process for working on them. This was shot down. On the other side, the website working group started a separate effort around documentation, which included a different tool for generating HTML content. We now have two tools (node's doc generator and the website generator) for generating documentation, each of which can produce documentation in a subset of desired formats, with different subsets of desired features, each of which is owned by a different set of maintainers — and it's producing an unnatural divide between reference docs and guides.

My recommendation would be:

• Form a docs WG,
• Which operates within the Node repo itself, while
• Giving the docs WG jurisdiction over changes in the docs/ and tools/docs/ directories.
• Place all docs within the docs/ directory of the Node repository.

[Qard]

@bengl I think of the docs repo as mainly just a place for high-level architectural discussion of the docs, which hasn't needed a lot of discussion, therefore it just seems quiet over there.

Much of the recent docs activity has been around writing and reviewing reference docs in nodejs/node. A lot of that has been reviewed by members of the @nodejs/documentation team, which are the folks managing the docs repo and working group. There's also been a few discussions that migrated from the docs repo to nodejs/node.

I think having a team of people with a consistent vision/understanding of what direction the docs should take when reviewing PRs is value enough on its own to warrant a WG.

[rvagg]

@chrisdickinson this is still on ctc-agenda, I'm going to leave it up to you whether you think it needs to stay for another round of discussion, my sense is that it's progressing but the agenda for this week is light so if it would help we can cover it again.

[bengl]

I've updated the bullet-point language a bit, on advice from @chrisdickinson. This original version is still available, for reference.

[indexzero]

@bengl +1 good update.

[chrisdickinson]

From the most recent CTC meeting it seems like all of the concerns have been addressed, and the resolution was to take the discussion back to this PR.

I suppose the question is: is this ready to be ratified? What are the next steps?

[rvagg]

This is still on ctc-agenda fyi, it's going to come up again, if it's not ready then we can punt again but there is an opportunity to close this out if everything is in order.

[bnoordhuis]

LGTM for posterity.

[chrisdickinson]

Per the resolution in today's meeting, I will merge this now.

[chrisdickinson]

Merged in 9cd4b76.