I am thinking about creating a user manual for Mail-in-a-Box. Specifically, for V0.40. I am thinking of writing it in such a way that you could both print it out into a booklet AND easily read it in HTML or in PDF format. I am trying to draft ideas about how to structure it best, because we have all read good manuals and we have all read bad manuals. My question is: what differentiates between a good manual and a bad manual, and how can we implement this for the mail-in-a-box project?
So I have a few ideas. Firstly, I think we should make at least one assumption when making the manual: the user is convinced that they want to host their own mail server already. Maybe we could include a sentence or two on page 1 in a “preface” or “introduction” sentence about why people use mail-in-a-box, why it’s awesome, what it is, and why the user should use it. But it should be short.
Secondly, I think we should use a word processor (like Libre Office, Google Docs, or Libre Office Online/Collabora Online), so we can focus most on typing, getting the words right, and organizing the flow of the document. We can then decide, once the wording and organization are right, to then copy and paste it into another form (like HTML, Markdown, PDF, etc.). I think it’s a major distraction and waste of time to try and edit an HTML document (before writing down English), because you are then half focused on organizing HTML, and half focused on writing good documentation.
First, I want to hit the important topics. I’m going to create another topic to create an FAQ (Frequently Asked Questions) and any other potential questions people have about mail-in-a-box that we could include in the manual.
Once I have questions compiled, we can organize it and start working on creating a manual. I am thinking we could either do a Google Doc, someone host a Nextcloud/Collabora server, or just edit it using Libre Office (or Microsoft Office) and upload the changes to a Github repository. I think Github is most preferable (maybe it will be a disaster if images get added? I would want to see the git changes, which might be ugly with images added to it.).