5

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:

  1. Collaborative: People can suggest revisions that can be merged in (e.g., via track changes, change requests, etc.)
  2. Reviewable: Changes are not immediately applied to the public handbook, but are stored separately for review and approval.
  3. 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.

1 Answer 1

1

You can store raw latex files in a GitHub repository to allow collaborative editing, version control, track changes, etc. The drawback is that only people quite familiar with Git would be able to contribute.

Then, there are some online tools able to generate PDF from latex sources stored in the GitHub repository (e.g. LaTeX.Online). I haven't tested it myself, but it seems like it allows you to create single link which compiles the source every time you visit it and outputs PDF file.

Alternatively, you could set up a GitHub Actions to compile a source code to a PDF file (e.g. after every new commit in the main branch) and upload it somewhere for online viewing. In the link attached there is a suggestion to use additional branch and GitHub Pages to allow online viewing of the compiled document. While it may require quite a lot of work to set everything up and working, once done whole process of compiling and updating would be fully automated. This is the way I would personally recommend - compiling would take place on the GitHub servers and user would always have ready and compiled PDF file available for viewing.

2
  • I would only add that to those less tech savvy, git + some WYSIWYG editor for whatever files they have to work on is a workable solution, long as those files are "dumb" enough to not trigger a barrage of replacements each tiny diff. Markdown format looks fairly reasonable for this purpose but I haven't personally used this setup yet.
    – Lodinn
    Jan 17 at 10:52
  • I think that the barriers for having people need to understand Git would likely be too high. I could do some scripts that scrape something and put it into Git for the purposes of generating something else though via Github actions (and for versioning). For example, a CMS-driven site where people could edit freely (draft) like a Wiki, which then has some approval process to dump that to Git and publish to a non-collaborative release + PDF. Though at that point, one wonders if there's just a CMS that can tackle the extra steps well.
    – Namey
    Jan 18 at 7:47

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .