| Author: | Daniel Beck |
|---|
Daniel is a technical writer, and he’d like more writers to contribute to open source projects. He can program, but writing is what he does best. And he’s seen writers be rebuffed and rejected with things like
There’s a lot of effort and energy being squandered or rejected, and that’s a problem. Daniel was a technical communication major, and did a lot of project based coursework. Those projects were never around open source projects, due to these experiences (and that’s approx 100 hours of work that could have been applied).
What can you do?
You can write better user guides by:
| Author: | Bart Massey |
|---|
About two years ago they decided to try to address the issue of poor documentation and small contributor base. Based on the idea of the GSoC Book Sprint, but had to be virtual because of scheduling and travel. Two days, effectively 3 people (had hoped for half a dozen?). Used Gobby, Markdown, Sigil, and Inkscape, and wrote about 40 pages of developer documentation.
Two people wasn’t really enough: people should be committed to participate for the entire time. It might also be interesting to try and pair people locally, so virtual, with local pairs. And having the tools tested and solidly in place and tested is important. Nothing will happen post sprint.
| Author: | Eric Redmond |
|---|
An FAQ is a bad code smell, a bad documentation smell. It’s a sign that the docs aren’t put together well and don’t actually answer the questions. It’s a sign of cargo-cult documentation. You’re starting a new project, so by definition there are no frequently asked questions, but you’ve seen others do it, so you think it must be useful!
Also, there’s an FAQ markup language: FML.