Documentation WG Status

[williamkapke]

@eljefedelrodeodeljefe mentions that the Documentation WG has stalled and wants to know what to do to revive it.

Opening here for CTC review and discussion.

For reference, here is the WGs charter:

The Documentation Working Group exists to support the improvement of Node.js documentation, both in the core API documentation, and elsewhere, such as the Node.js website. Its intent is to work closely with the Evangelism, Website, and Intl Working Groups to make excellent documentation available and accessible to all.

Responsibilities include:

• Defining and maintaining documentation style and content standards.
• Producing documentation in a format acceptable for the Website Working Group to consume.
• Ensuring that Node's documentation addresses a wide variety of audiences.
• Creating and operating a process for documentation review that produces quality documentation and avoids impeding the progress of Core work.

[bnoordhuis]

The documentation and the website seem to be in good shape so even if the WG isn't very active, individuals certainly are. Perhaps we don't need a separate WG.

[cjihrig]

This seems like a situation similar to that of the Testing WG. There haven't been any meetings lately, but the tests get a pretty good amount of attention. At this point, it more serves as a "who to mention" for tests PRs. It seems to be working out fine.

[Trott]

It's not clear to me from the comment that @eljefedelrodeodeljefe is actually trying to figure out how to revive it, but if so:

Maybe a good first step for someone who thinks the WG needs to be revived would be to identify the things that aren't happening that the WG should be doing. Additionally, perhaps they can reach out to people who might be interested in doing the work (existing WG members, sure, but also others).

I would welcome a more active Docs WG. There seems to always be a timely response when I @-mention testing or build, but a number of my @-mentions for docs go unanswered. Recent example: nodejs/node#9552 That is the type of thing doc folks should be all over, I think. (In fairness, it is a holiday weekend in much of the world right now, but that doesn't seem to affect it when I @-mention build or testing or CTC or website.)

Possible things that @eljefedelrodeodeljefe or someone like them might want to see happen:

• Does the Style Guide need updating? Should it be moved to the main repo so people know that it exists?
• Would @ChALkeR benefit from a docs champion helping to move the mdlint/doclint/whatever-it-is-called Makefile rule forward and expanding the ruleset in the markdown linter so that it conforms to the Style Guide?
• Internationalization?
• Perhaps the entire docs should be copy-edited by a WG team every X months to weed out errors, confusing formulations, comma splices, awkward phrases, inconsistent capitalization, and that sort of thing?

[Trott]

One other thing: I do believe that @chrisdickinson acted as the (unofficial?) chair of the Documentation WG. It may be good for whoever cares deeply about the WG to identify someone else who can play that role. (If Chris wants to spring back into action and push things forward on docs, great! But I wouldn't expect that soon. And even so, always good to have a known back-up.)

[Trott]

Oh, I guess this should have been an obvious move: @nodejs/documentation

[sam-github]

I'm interested in documentation, and have time to review doc PRs, and I keep my eye out for them. I declined an the initial WG invitation because I don't have time for much more than PR review, and it sounded like the WG needed greater time commitment.

[eljefedelrodeodeljefe]

@bnoordhuis that is the case, so there is definitely no urgency behind it. However the goals of the WG had are definitely also not being worked on. Dissolving it is one viable option, minus: leave the GH team for notification purposes.

@williamkapke @Trott yeah, I don't mean to necessarily revive it, and also I am probably the worst person for the job, as I am, ...too German... too direct. In general it would be just good to deal with it.

However I think the goals still are valuable to be discussed and I don't think this will happen with much attention in the CTC meeting. For me positive goals are:

• integrating guides
• working on the doctool. @addaleax and I had some ideas, but never did anything.
• working on the presentation of the API side. Having worked on it I can tell that this is a major construction site, dating back 2011 and only being patched now and then.
• being a shining example of documentation (projects like Kubernetes, would be a good example)
• i18n
• maybe switching even from outdated markdown toolchain. I was working on some, but feared the trouble putting it up

non-goals are:

• polluting the git tree with even more tools and patch work. This is rather controversial, since we see commits for remark integration from @ChALkeR. I pledged to not integrate it.
• lack of leadership. I guess there were personal, not associated reason, that led @chrisdickinson not to take it, which is okay.

A clear mandate from CTC would be good and not the "it's not too relevant for us" or "looks good as it is". Also rather controversial is my opinion that the general toolchain, but especially the API stuff should not be driven from make.

As it stands now, getting rid of the group is a safe thing to do. A pity though.

[Trott]

@eljefedelrodeodeljefe If I'm understanding you correctly, un-chartering the WG is a legitimate possibility, but not the best outcome in your opinion. Can you provide some specific suggestions for actions the CTC might take here that would be better in your opinion?

[hackygolucky]

Are there folks in the CTC who would instead champion efforts around Docs? I'm wondering what the benefit vs. the cost of de-chartering this group would be. While there has certainly been low activity in the Documentation WG this year, I think there are steps that could be taken such as outreach to make sure there aren't folks out there(maybe who aren't currently in the CTC) that would have interest in helping out.

There are definitely challenges with contributing to Documentation, but it's also an area in open source that can have a lower barrier to contributing. Sometimes folks just need to know they are needed. In noticing that there was such a low activity, I had hoped for 2017 to organize an 'International Documentation day' similar to NodeBots or NodeSchool day to get folks interested and educated on how to contribute to docs, but there has to be a core group of folks who can lead and help with that as well.

[eljefedelrodeodeljefe]

@Trott nah, I think all of these options are okay. To have a viable WG I though think that a clearer mandate would be good. previously Chris could have provided or at least be able to get it from the CTC, but this is no longer an option. E.g. a WG should be able to make decisions like: "let's get doc tooling out of the tree and rather npm install it."

[kahwee]

I think we all had ideas and lack a strong leader to push this through. Like @eljefedelrodeodeljefe said we aren't sure if we can make decisions like getting the doc tooling out of node project. I spoke briefly to Myles about this as well and I don't think we had a conclusion, I didn't followup on this.

[Qard]

I was one of the people initially very active in the Docs WG, though my involvement in Node.js core in general has been rather low as of late. I have a lot more time available now though, so I might be able to help out again.

I think one problem is actually in the branding of the group. The "docs" label seems to suggest to a lot of people that it's just focused on reference material, but a major intent of the forming the group in the first place was to produce higher level guides and other educational material. Perhaps expressing it as an "educational materials" working group would be better? I also feel like it should coordinate more closely with evangelism and inclusivity working groups along with the other learning initiatives such as Code and Learn.

As has been hinted at already in this thread, the reference docs aspect of things has been moving along fairly smoothly for awhile now. I think that has actually contributed to the seeming lack of urgency to continue arranging meetings, which is problematic for making progress on the larger projects that need doing.

I don't feel like I'm the best person to be leading the group, but if no one else is willing to step up, I'll volunteer to fill the seat the best I can. As someone with no particular professional motivation for involvement though, I'd really like to see someone with employer support able to fill that seat though. It'd be more stable long-term that way.

[williamkapke]

There was a pretty large group of people at the table yesterday (Collab Summit)!

Sorry you weren't able to join them @eljefedelrodeodeljefe

Great work WG! I hope this rally does the trick.