Kickstarting the documentation authoring effort

Hi folks, 

I've set up a GitHub repository[1] to get started on the doc authoring effort.

The goal of the effort is to have all our cross-WG documentation needs for testing stored in one place, easily editable by the community.

In order to do this we need to centralize, update and improve existing documentation, and author new content when existing resources are lacking.

To kickstart this project, the Resource Center TF has helped gather a list of existing related docs[2] along with a second list of docs that need to be written. I converted the latter into GitHub issues[3]. Bin Hu's been assigned most of the work here (he volunteered), but I'm sure he'll appreciate your help. Please sync up on the issues directly if you want to pick up some work. Generally, that'll imply looking at the existing docs[2] to find relevant content, using an online service[4] to convert it to markdown, copyediting it, adding YAML front-matter to it[5], and sending a pull request. More info in our contributors' guide[6].

Note that we choose to go with Markdown files and a static site generator (Jekyll). This it has the advantages of being a highly portable solution and to be really well integrated with GitHhub making deployment and hosting trivial. (Don't worry, we'll still have our own domain name).

Initially the project will happen in two phases[7]:

1) we'll get the basic documentation ready for launch along with layout and design (more on the latter more in a follow-up email), and,
2) where appropriate, we'll remove/redirect/amend exiting content to make sure all content points to the new canonical source.

We'll work iteratively thereafter.

Happy to answer questions.

Best,

--tobie
---
[1]: https://github.com/w3c/ttwf-docs
[2]: https://github.com/w3c/ttwf-docs/blob/gh-pages/RESOURCES.md
[3]: https://github.com/w3c/ttwf-docs/issues?labels=authoring&page=1&state=open
[4]: http://fuckyeahmarkdown.com/
[5]: http://jekyllrb.com/docs/frontmatter/
[6]: https://github.com/w3c/ttwf-docs/blob/gh-pages/CONTRIBUTING.md
[7]: https://github.com/w3c/ttwf-docs/issues/milestones

Received on Thursday, 30 May 2013 16:43:04 UTC