doc: add Docs working group #4244
Conversation
|
|
||
| Its responsibilities are: | ||
|
|
||
| * Defining and aintaining documentation style and content standards. |
There was a problem hiding this comment.
whoops! (although aintaining sounds funny) will fix.
|
Couple nits but LGTM |
|
@jasnell cool. nits addressed. |
|
@nodejs/ctc |
jasnell
added
doc
|
|
||
| Its responsibilities are: | ||
|
|
||
| * Defining and maintaining documentation style and content standards. |
There was a problem hiding this comment.
Would "content structure" fall under style?
There was a problem hiding this comment.
I'd think so. I'll add it in to clarify.
|
additional changes still LGTM :-) |
|
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? |
|
An incubation period for WGs would be good. But also keep in mind that we
|
|
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 |
|
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:
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. |
|
@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. |
|
@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. |
|
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. |
|
@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? |
|
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 |
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:
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. |
|
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. |
|
Charlie, I don't believe it's a reluctance to see the work move forward but
|
|
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:
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? |
|
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":
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:
|
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.
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.
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. |
|
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:
|
|
@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. |
|
@chrisdickinson this is still on |
|
I've updated the bullet-point language a bit, on advice from @chrisdickinson. This original version is still available, for reference. |
|
@bengl +1 good update. |
|
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? |
|
This is still on |
|
LGTM for posterity. |
|
Per the resolution in today's meeting, I will merge this now. |
|
Merged in 9cd4b76. |
PR-URL: #4244 Reviewed-By: Ben Noordhuis <[email protected]> Reviewed-By: Chris Dickinson <[email protected]>
PR-URL: #4244 Reviewed-By: Ben Noordhuis <[email protected]> Reviewed-By: Chris Dickinson <[email protected]>
PR-URL: #4244 Reviewed-By: Ben Noordhuis <[email protected]> Reviewed-By: Chris Dickinson <[email protected]>
PR-URL: #4244 Reviewed-By: Ben Noordhuis <[email protected]> Reviewed-By: Chris Dickinson <[email protected]>
PR-URL: #4244 Reviewed-By: Ben Noordhuis <[email protected]> Reviewed-By: Chris Dickinson <[email protected]>
PR-URL: nodejs#4244 Reviewed-By: Ben Noordhuis <[email protected]> Reviewed-By: Chris Dickinson <[email protected]>
PR-URL: nodejs#4244 Reviewed-By: Ben Noordhuis <[email protected]> Reviewed-By: Chris Dickinson <[email protected]>
PR-URL: nodejs#4244 Reviewed-By: Ben Noordhuis <[email protected]> Reviewed-By: Chris Dickinson <[email protected]>
Proposed charter for Documentation working group.