This is a question for anyone who has had to maintain a set of guidelines or handbook which might be fairly long (book-length) with multiple sections. The ideal case would be a system where revisions can be suggested, but not immediately viewed by end-readers of the handbook. After approval, suggestions would be reflected in the handbook. Using this model, the handbook could be collaboratively improved over time. From what I can tell, systems like GitBooks and some other tools built for software documentation have these capabilities.
However, as a handbook rather than code documentation, it is also important that you can dump the whole thing into a reasonable, readable form such as a PDF that can be shared. Unfortunately, this second requirement seems harder to find in the collaborative space. While GitBooks meets some of the first criteria, I was not impressed with their PDF's (some failed to generate, other projects had images broken up across page breaks). One could theoretically do this with scripts and Google Docs or a Wiki (e.g., people edit willy-nilly on drafts of each section, where a script copies those into a single master document for new releases).
I am hoping that I am missing something though, and that other people have found good solutions to this problem. So then, what strategies have people tried for maintaining handbooks that should be updated through suggestions or community collaboration which have these characteristics:
- Collaborative: People can suggest revisions that can be merged in (e.g., via track changes, change requests, etc.)
- Reviewable: Changes are not immediately applied to the public handbook, but are stored separately for review and approval.
- Single File Export: The whole handbook can be exported in a reasonable single file for reading, such as a PDF or similar document. This document should be reasonably formatted (such how LaTex works) rather than look like you took a single-page HTML file and pretended that is readable as a PDF export.
