search

w3c / modern-tooling

Work of the modern tooling task force
http://w3c.github.io/modern-tooling/
MIT License
44 stars 39 forks source link

W3C developers landing page: nicer documentations for our developer tools #35

Open gbaudusseau opened 9 years ago

gbaudusseau commented 9 years ago

the documentation is very important if we want get contribution from the community. I suggest to move all the documentations (and unified the designs) on the developers tool landing page for each W3C open source tool.

In that way, it will be easier for people to complete the doc, add installation tutorial etc...

darobin commented 9 years ago

I like the idea of unified design, and the unified build tools to go with so that people don't have to worry about how to make them look good and all.

My concern here would be about 1) managing all of that content in a single repo and 2) separating the docs from the code.

Having a single repo for unrelated deliverables is a problem because branching doesn't work well, it's a lot easier for people to conflict or screw up, etc. Likewise, separating docs from code can easily be a problem — for starters it becomes difficult to require people writing new features to also produce the docs to go with (in the same PR).

Perhaps this could be built by convention: every tool must have a docs directory that's filled with Markdown (or whatever is convenient). Those are pulled automatically and regenerated when need be. WDYT?

gbaudusseau commented 9 years ago

Yes, create a convention like have a docs directory in each tool repo sounds good. I am just wondering where should we store these conventions (unified design for tools, documentation directory and design, content...)?

darobin commented 9 years ago

Just have a docs directory in the landing page repo :)

gbaudusseau commented 9 years ago

approved! :+1: