Hi all, I've recently been considering building a reprap and have been going through all the documentation pretty rigorously.
I'd like to make a suggestion about the style of documentation.
While the actual writing is great, I found the organization to be very confusing. I would suggest organizing the document in a fashion similar to what we have on the 'darwin build instructions', but locking the document and all referenced documents to a specific revision. Any other documents should be clearly marked as beta or development. Each set of documents and referenced documents should also specify what version it applies to. If there are changes made to the document, a new version should be started and clearly marked as unstable and also not be linked to unless through a development page.
This is similar to the software engineering concept of beta vs stable. While important changes are made to stable releases, such as security updates, any new documents or changes to referenced documents are marked as beta.
The advantage of doing this is to keep documentation consistent across the project. For example, I've noticed that the software install instructions ask for java3D 1.5.1, while other documentation suggests using 1.4 instead. Similarly, the sanguino and the arduino and the PIC build instructions have issues with consistency.
Marking documents as locked and specifying specific document versions shouldn't be difficult, since the wiki has the versioning functionality built in.
The disadvantage that I can see is that there will probably be less work done on the documentation by casual users. If there is a modification someone wishes to make, they would need to re-read the beta documentation and make changes there instead of on the stable documentation. However, as stated above, projects which have multiple dependencies through multiple pages (like ours) face inconsistencies very easily when one page is updated and another is not.
Another disadvantage is that there would need to be a person or team to take ownership of the documentation process and to verify, lock, and release each document version. I'm not too sure what the current structure of the reprap wiki is, but there seems to be lots of active people on the boards and in the community that could lead this.
What does everyone think? Is this a worthwhile endeavour to take?
Matthew
