Documentation is the castor oil of programming. Managers think it is good for programmers, and programmers hate it!Jerry Weinberg, Psychology of Computer Programming
Chris opened bug 283734 “Documentation Best Practices” to see if there is a way to move maintenance of project documentation to the wiki. The idea is to allow the eclipse user community and developer community to help keep the eclipse documentation more current and relevant. Many projects are overwhelmed with the number of bugs and enhancement requests they have to try and keep up with, so working on documentation is the last thing they think about. Currently during development most projects put this off until M7, however, from my experience very little documentation is done during M7, or any of the release candidate phases.
During the last Architecture Council call they agreed that this was something we should pursue. So, I volunteered to help come up with some guidelines for how the documentation should be handled from the wiki. To this end, I have started the following:
The work is based partly off of some existing documentation from the Fedora Docs Project as well as the Ubuntu Documenation Team pages. Both of these projects leverage their community to help keep the documentation current and relevant. The documentation is started on the wiki, and then moves through some phases to get to it’s final publication. Eclipse is already getting great community help with the Babel project, so I think this is another easy win situation for the community to help out. The nice thing is that you do not need to be a committer to the particular project that you are writing documentation for. If you see something wrong or missing, feel free to update it.
Committers and PMC should keep an eye on their wiki documentation pages, and I suggest producing the final version from an approved snapshot of the wiki site. The purpose of the Documentation Guidelines is to provide the relevant information that projects will need and contributors should follow. We want a professional consistent look across the documentation.
Please feel free to comment on the bug that Chris started, and contribute items to the Documentation Guidelines. It is going to be what we make it.