This repo needs a readme!

[Frijol]

I came to this repo hoping to help out with docs-writing, read the CONTRIBUTING.md, and then started poking around the repo looking for examples/some idea of the state of things.

All I found were mystifying nested folders and some old discussion on the issues. What now?

Let's put a readme in place so nobody gets lost. It can be very basic, but needs to include such information as:

• What is the state of the system? Based on reading the issues, it seems we may still be pretty preliminary– is that correct?
• What's a good entry point? Are there specific docs we're hoping to see written, or certain issues that need hashing out? Point me!

Onward and upward!

[Qard]

Yeah, it seems to me that GETTING-STARTED.md and CONTRIBUTING.md should be probably part of README.md, or at least referenced in it.

It is indeed a bit preliminary. Some docs have been put together, but I think there was a bit of uncertainty how this would all fit together post-foundation-merge. Now that node 4.0.0 is out, I think that picture is becoming clearer and we should probably do another docs meeting to discuss the road forward.

As for an entry point, Issue #1 has a link to a trello board where we compiled a wishlist of sorts for what we want documented and roughly what sort of structure we think would be most effective. I've mostly been focused on documenting internals to lower the barrier to entry for new contributors. We need all sorts of content though.

[danielkhan]

I agree with @Frijol and @Qard. For me it was a bit confusing that we had quite a discussion on if I should cover installing io.js in the installation doc just to later find out that the docs don't yet end up at the new website for 4.0.0 anyway. Now having only to cover 4.0.0 is a relief, though.

Unfortunately I haven't yet understood the context in which for instance a installation doc will be shown.
If someone could show maybe another project that accomplished what we want to achieve it might be easier to jump in. But that's just my opinion - I'm not sure if I'm the only one feeling a bit lost.

[Frijol]

right with you @danielkhan on feeling a bit lost!

[Qard]

A lot of the discussions around technical ideals for the docs structure and design have referenced the Rust and Django docs. Those are good places to look for what we think are docs done right.

[mikeal]

Frankly, I think this repo has been way too focused on tooling when what we really need is content.

If the current tool isn't finished I think the simplest one imaginable should be created and we should start doing outreach focused on building and improving content which is visible on the website. Tooling can be improved later, the important part is building a community around created and improving the content.

[Qard]

👍 More content is exactly what I want to see.

[mikeal]

Can someone tell me the state of this repo/project? It seems like it's just a bunch of empty directories?

I'm concerned because there's a ton of people trying to do things in Issues with no real path to getting anything done. Documentation is becoming an increasingly hot topic and it seems like the undefined state of this WG is holding back contributions.

[Qard]

Agreed. It seems there needs to be some coordination with the website wg to get this stuff online, but that's just not happening, for some reason. There also hasn't been a meeting in awhile, which needs to change.

[bengl]

This repo has a README now so closing this. @Frijol since you expressed interest in helping out, please have a look here: nodejs/node#4573