Documentation Discussion during diagnostics WG meeting

[mike-kaufman]

This issue is a result of a discussion that came up in yesterday's diagnostics WG meeting. Per nodejs/diagnostics#92, the diagnostics WG would like to get better instructions and how-to guides for common diagnostics tasks. E.g., how to do performance profiling, heap profiling, etc.

A few things came up in the discussion:

1. There's an opportunity for "more professional" documentation. While an individual doc may be technically accurate, it can lack a level "professional quality" in terms of readability, content flow, structure, etc. Moreover a set of related docs can lack consistency. (sorry, no concrete examples came up)

2. This is an opportunity for project contributions from non-developers - e.g., technical writers or others looking to get involved in the Node project.

3. There's not currently a good way to track docs-related/tech-writing related contribution tasks, e.g. a "tech-docs" label. (Or is there?)

4. Would the project benefit from some contracted (i.e., hired help) to move this forward?

We decided that some of the questions here are beyond the scope of the diagnostics WG, so we thought we'd open up an issue here & see if this can be driven forward as part of community-committee work.

/cc @nodejs/diagnostics

[Qard]

I don't think it needs a new label, we could just open some issues on http://github.com/nodejs/node with the doc and help wanted labels.

[mike-kaufman]

I don't think it needs a new label, we could just open some issues on http://github.com/nodejs/node with the doc and help wanted labels.

Yeah, that may be sufficient. I probably didn't word things correctly above - my take-away from yesterday's discussion is

• it wasn't obvious (at least to me) precisely where we needed the "professional-level" help that a contracted docs person would bring
• this is broader than the diagnostics context we discussed yesterday
• Identifying such areas is useful both for a scoping exercise (i.e., what would a contracted docs person do) as well as identifying areas for community contributions.

LMK if there's a different understanding here.

Perhaps it's possible to address above via specific issues outlining concrete tasks, and a new tag isn't necessary.

[bnb]

@mike-kaufman So you're looking specifically to improve docs for the Diagnostics WG projects, or Node.js in general? Getting explicit scope would be extremely helpful. ❤️

If you do have specific scope in mind, I think it would be most helpful for someone that is looking to jump in to contributing to have an outline of what you're looking for and an individual they can reach out to (even if this is you) if they have explicit questions. Do you think those are possible?

[Qard]

The initial discussion was sparked by improving diagnostics-specific docs. Not projects though so much as contributing guides for the website to introduce diagnostic-related concepts to users.

We brought the discussion here because there was suggestions that a proper tech writer could help with this, and that would be more relevant at the org level than just specific to diagnostics.

[mike-kaufman]

We brought the discussion here because there was suggestions that a proper tech writer could help with this, and that would be more relevant at the org level than just specific to diagnostics.

In particular, the discussion was that improved docs would a) help the node developer community and b) were good opportunities to engage non-coding contributors. Both of these were considered a good opportunities for the community-committee to drive. Thus the issue here.

[bnb]

Huge +1 on this, in that case. Since you do have specifics in mind, do you think you (as the Diagnostic WG, not necessarily you as individuals) would be able to help provide an outline of the information that needs to be created?

[naugtur]

Speaking of specifics, the whole thing started with some guides I'm writing in my spare time: https://github.com/naugtur/node-diagnostics-howtos
Now proposed as a contribution to nodejs.org guides
nodejs/nodejs.org#1444

I'm not a native speaker of English and there's likely a lot of people with better writing skills, but I'm hoping my work could provide more than an outline.

The scope (i.e. which topics I wrote go in, which should be added) needs more discussion in nodejs/diagnostics I guess.

Also, let me relay what I heard in the Diag WG meeting. We're looking to establish a process for this kind of collaboration on writing and maybe let it spread in the organization if it works out well.

[bnb]

@naugtur Hey there! Wanted to check in and see if there's been any updates on this - would love to see if we can support the Diagnostics WG further, especially now that we've been working to establish better processes around initiatives.

Also, let me relay what I heard in the Diag WG meeting. We're looking to establish a process for this kind of collaboration on writing and maybe let it spread in the organization if it works out well.

If this is still what we can help with, awesome - we can begin working to find a champion and moving this forward.

[naugtur]

To my best understanding status is as follows:

• The pull request with first of my guides is here Add first of the new diagnostics articles to guides nodejs.org#1444 ready for editing help.
• @mike-kaufman should be able to chip in on the status of diagnostics WG talk about this, I missed some recent meetings because of a new Distraction named Alice (I'm a father! yay)
• I'm still planning on contributing more guides as soon as we have the process in place.

Not sure where the initiative is now. If I need to do anything to move this forward, please explain. I thought the next step is for a person willing to do editing/style/technical writing to emerge so I can work with them to get the content to ~perfection.

[mike-kaufman]

I thought the next step is for a person willing to do editing/style/technical writing to emerge so I can work with them to get the content to ~perfection.

This seems like a valid next step to me. @bnb - any suggestions for how to best recruit some tech writing volunteers that can help here? Seems like a great opportunity for

• someone who can propose some consistent styling for how-to's like this
• someone to do some editing/tech writing.

If someone was interested in this, how would they find this opportunity? Is there a landing page someone for "how to get started with tech writing contributions to node"?

[mike-kaufman]

I see this is on the agenda for the 2018-01-11 CommComm meeting (#213). I'm not able to attend, but I'll post a few comments here:

This issue was opened as a specific example, but more generally can be framed as a "recruiting" problem, i.e., how does someone with a tech writing/documentation background discover opportunities like this and then get involved?

IMO, from the CommComm perspective, this is the thing to focus on. It aligns nicely w/ CommComm goals of increasing participation and increasing contributions from a diverse background of skillsets/talents. It also aligns nicely w/ other initiatives like #203 - if "recruiting" is a high priority, how does a website redesign accommodate it?

/cc @bnb

[bnb]

Thanks @mike-kaufman - I will raise your comments in the meeting 👍

[bnb]

I am going to pull this off the agenda for now. We've discussed it in a few minutes, but I don't honestly know if any individual has the time to dedicate to this at present (as far as I know, nobody has explicitly volunteered). I definitely think this is a good initiative, but it doesn't seem like we're ready to take it on.

[mike-kaufman]

ok, feel free to close this if itsn't actionable enough

[bnb]

Thank you @mike-kaufman. We'll definitely keep it on the back burner and ping y'all when we've got enough time to help ❤️