An owner for the docs

[piscisaureus]

Nobody really "owns" the docs.

When I review a docs PR (and there are plenty) I check only for factual correctness. Nobody really looks for consistency in writing style, presentation, order etc.

It'd be great if we could find someone to fill this role.

@mikeal @iojs/tc

[chrisdickinson]

I talked with @mikeal a bit about this: I think one issue we have is that the current tooling doesn't make it easy/possible to build out the kind of docs that we've been historically weak on (tutorials and overviews). I started down the path of creating a docs WG, but stopped because at the moment tooling is the primary concern, and that runs headlong into the website WG. I'm currently seeing if they would be willing to adopt the docs tooling. Once we have that set up, the idea is that we would spin out a docs-only WG that was unconcerned with tools.

[chrisdickinson]

... that is to say, I totally agree, we should have a documentarian-in-chief (or, at least, a docs WG); the above is just to give context of where things are at now.

[osslate]

I'm interested in looking over documentation, cleaning it up, elaborating/simplifying when needed and making sure things are consistent.

[mikeal]

The website team is currently tasked with:

• building tooling that can support i18n and produce a variety of pages with consistent design
• fostering a translations community
• writing content (FAQ) and messaging

There's a lot of overlap with what we want out of the docs. It makes sense to me to hand this off to the website team with the expectation that as the list of documentation editors grows it will probably necessitate its own WG.

[rvagg]

I mostly agree with @mikeal about the spin-up process here but I would fully expect that the docs team will need to be separate sooner rather than later. The overlap in expertise and skills between website and docs isn't large enough to warrant it being in the same WG and I'd like to see docs being mainly handled by people like @expr (who I fully endorse for involvement in this!) who have a skill for technical writing and managing a large body of documentation.

@expr: perhaps you should start poking around in iojs/website and start contributing there, specifically around docs. There's also the https://github.com/iojs/doc-tool repo that will be part of this.

The ideal would be that the flow of docs could be reversed like we're doing with readable-stream such that any changes (and associated discussion) to docs happen in another repo and iojs/io.js is only concerned with pulling them in for releases.

[mikeal]

I would fully expect that the docs team will need to be separate sooner rather than later.

The website team is currently handling 3 things: tooling, messaging and content. Eventually I expect it to only handle tooling and to collaborate with WGs who deal with messaging and content.

In the short term, the easiest mode of collaboration is to have people concerned with messaging and content in the website WG so they can influence the tooling directly as it is built out and make consistent improvements to messaging and content that is already there.

I want a giant docs team, like FreeBSD big! I think that once the tooling is ready content contributions will be so much simpler that we'll see a flood of new people, necessitating another WG to manage the contributions.

And don't forget about i18n. Of everything we're talking about this is the most specialized kind of contribution and I'm hoping we can find compelling ways to grow a big community of translators.

@expr if you're interested I can file and issue proposing you be added to the website WG :)

[osslate]

@rvagg I'll pull the repo shortly and poke around.

@mikeal sounds good to me! Go for it :)

[rvagg]

re i18n: I've added 10 new collaborators to learnyounode in the last week, people I've never had any interaction with before, they've all contributed translations or part of translations that I can't read a word of so I'm completely offloading any responsibility for wording to these people! It's like the project has a bunch of new mini-WGs internally that have to take responsibility for discussing and adjusting wording as issues are filed.

Extremely exciting and it'd be awesome to have that same thing happening here!

Perhaps I should ping @martinheidegger into this discussion who spearheaded the i18n tooling in workshopper & learnyounode. Doing the same for core doc tooling would be awesome.

[chrisdickinson]

The ideal would be that the flow of docs could be reversed like we're doing with readable-stream such that any changes (and associated discussion) to docs happen in another repo and iojs/io.js is only concerned with pulling them in for releases.

I'm okay with the doctool going this route, but it would take a lot of convincing for me to come around to removing the docs from the iojs/io.js repo itself.

[mikeal]

it would take a lot of convincing for me to come around to removing the docs from the iojs/io.js repo itself.

I'm also not sold on this. In particular, I think that new features and API changes/enhancements should come in a PR that includes the doc changes which isn't possible if we put them in their own repo.

[cjihrig]

I'm also against moving the docs out of iojs/io.js for the same reasons.

[martinheidegger]

There are three reasons I can think of why one would want to split the documentation into an own repo:

• Issue management: (International) documentation will come in a lot of issues. Having them in a different repo might be comfortable for other collaborators because of the noise they create.
• The git repo size. Downloading and storing it locally code and documentation will be a file size issue preferably sooner than later because of images etc. (making it hard to work on it).
• Build tools. For good i18n we will need some additional build tool to generate the docs as well. Those build tools would need to be used by the doc writers. Having a separate repo increases the chance imho that a good build tool will be available.

All those issues are comfortability issues. They come with two big problems imho:

• Just by looking at the iojs repository one will not see the latest docs for iojs and wonder where they are
• The repositories will be inherently differently versioned, opening the the door for version problems.

The later one can be crucial. Trying to make sure that this actual iojs version is with that actual documentation version can be difficult. In my opinion it would be good to have those issues addressed (conceptually) before moving the docs out of the repo but else I prefer a separate repo because of the user management.

re i18n: Sure, I can help out with translation.

[ThisIsMissEm]

I had been interested in working on docs and heading that up, and had several discussions with people at NodeConf.eu about it, however, contracting appears to be sapping my time from me.

I was also going to build a feedback tool for the docs, something we could embed and it'd give a way to annotate with Medium style comments as to anything that doesn't make sense or confuses the reader.

[julianduque]

@rvagg love the i18n suggestion, also would LOVE to help with spanish translation of docs and website

[sam-github]

I'm -1 for removing reference/API documentation from io.js source repo, having them there allows very simple verification that APIs are documented in the same PR that introduces changes.

Guide style documentation, with higher level advice (the addon section approaches guide-like material), would be a good candidate for another repo. But that doesn't exist yet.

[snostorm]

It could make sense to allow the work docs work to happen in a separate repo if there was willingness to take on the overhead of keeping things in sync. For example, a subtree approach could be used in git to bring in squashed changes from the docs repo in to the main repo.

I see the addition of i18n variations and build/theme code as a lot of possible overhead for the main repo.

I suppose another variant of this idea would to explicitly bundling in static "exports" of the docs in to the repo and committing those:

Need to prep documenting a new API for an existing module?

• The docs team can draft/ready it in their repo (and try to get a head start on i18n)
• Before the new io.js version is allowed land with this change, we generate the latest docs branch EXPORT (from the branch which is following the release schedule) and PR the export to io.js.
• Release version 1.100.x (with both the queued doc changes and features.)

The nice this is that users fetching old versions of io.js will have a version of the docs HTML sitting on their machine, ready to be consumed. We could even used a simplified export "theme" over what appears on the web to keep the overhead minimal and very cross-device friendly.

But, perhaps this is just too complicated?

[sam-github]

Sounds too complicated to me. Might as well make competent doc authors collaborators, with the understanding the changes they can LGTM on are the ones within their area of expertise (docs). This is no different from any other collaborator. Drafting of changes can already happen on a branch/PR request. I think we lack content and doc authors more than we lack process.

[Fishrock123]

So currently @iojs/website has responsibility for docs (iirc).

It should be noted that we simply do not have the resources (i.e. people's time & energy) to actually do anything though.

[brendanashworth]

Looks like a WG has been spun up: https://github.com/nodejs/docs

Should this be closed?

[chrisdickinson]

Closing this for now. The docs are currently owned by the website WG, with the docs WG spinning up to take them over once the dust settles over there.

In the foundation-y future it might be good to look into creating an "editor-in-chief" role, but that should be broached as a new issue after the docs WG has a steady footing.