User Manual Creation

Improvements
1

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.).

2

As a guy who got straight Cs in 6 quarters of English and then an A in technical writing, I have one recommendation.

In school they pushed us to create an outline to help organize your thoughts. That was a great idea but a pain with pencil or typewriter.

Now we have MS Word or Libre Office Write. Both have great outlining features. You can promote and demote, rearrange, and cut and paste. Wow! This is so easy.

They both will create PDFs, my preferred file format.

I think every thing on the admin screens needs to be carefully documented. Click it to see what it does, won’t cut it. I hate some of the new Mac and Windows stuff where you Easter Egg hunt to find what something does.

Another pet peeve is red and green indicators. I am green blind, as are about 8% of the males in the US. Good HMI design requires status be indicated more than one way. Color is just one.

I also think the install process should create a detailed log of what happened. How can you do a postmortem if you don’t have a log. I have read there ways to get Linux scripts to log both commands and their input and their output.

Climbing down from my soap box…

Dennis

3

I so agree with this … I have written a guide to secondary DNS to replace the now defunct website which is listed in the install guide … it is down on “paper” in a document file … problem is I do not know how the heck to do formatting, or turn it into a proper html file, etc.

So, get the contents down - then find someone to do some magic to make it beautiful.

On that note, anybody willing to convert my document into something nice? :sunny:

4

I would be interested in looking at it. However, as @dwomack pointed out, we need to come up with an outline for this.

I would like to get the basics done first. How does the user get Mail-in-a-Box working? Then, once we get our outline of that, we get into advanced, troubleshooting and optional topics. But we can write those down on the outline below the basics, so then we can reorganize it when we have the basics done.

I’m thinking that for the beginning of organizing this, we should find a live collaboritive editor (i.e. Google Docs, Collabora, or Microsoft’s Whatever Online).

Once we have the outline, let’s use Libre Office and Github to make the content based off the outline.

So who would like to get behind this?

5

…So are any of you interested in getting behind this? Also, @alento, were you going to send me that guide about DNS?

6

Can we setup a public Bookstack for this? Makes it easy to collab in and export PDF’s for download later.

7

Yes, eventually … I was able to work more on it last week and determined that I had to make some changes … which I haven’t made yet. Once I do, the guide will be made available.

8

Okay, so I was waiting for a better time to discuss using Bookstack, @murgero.

My personal problems:
Firstly, I wouldn’t mind hosting it on any of my current Digital Ocean servers. However, that brings the question of reliability and security of me providing it. I am currently trying to reduce cost of my Digital Ocean account, but haven’t gotten around to it. I currently host 5 servers ($5/mo each, $10/mo for one), with a handful of snapshots on the account. I don’t know which servers to get rid of, or how to back them up (because you can’t download snapshots of the image), and I don’t want to add another server for this. Now, I have thought about combining servers, but I haven’t done any extra effort to secure any of the servers, so I’m in a bit of a personal mess right now. None of them are business-critical in certain senses, but I would like to not lose the data. Let’s not get off-topic here, so if you have any advice to offer, PM me or let’s start another side-thread.

After looking at Bookstack demo, it looks a bit complicated to operate. I am concerned it will scare off newbies, and/or no one will be willing to contribute to the manual to begin with. I kinda want to kick-off with an outline that we all edit at the same time (like Google Docs, which edits live documents that multiple people can edit at the same time). The only reason I ask who is willing to commit to contributing is so that if I set a live document up, I don’t want some 3rd grader to come online and troll with the live document.

Once we slap all our ideas onto a Live Doc™ (I will call it Live Doc (fake name) until we figure out a solution to use), we can start to argue and agree on what actually goes onto the outline, and in what order. Then, once we finalize the outline, we can split the work into the sections based on the outline, preferably through Github/LibreOffice. Now, I tested out Libre Office, and many of the formats are not human-readable (i.e. hard for a human to read the raw file), except for HTML. There is a small possibility that exporting documents in HTML format from Libre Office will screw up, so maybe we can keep the Github repository updated with both a .ODT/.DOCX/“ALL FORMATS” file and an HTML file based on the .ODT/.DOCX/“ALL FORMATS”. My only concern with uploading both is that I’ve read there are ways to bake into these documents malware, and it’s very difficult to detect if the file format is difficult to read.

So I wanted some sort of accountability (I know it is a small amount that can be achieved), so I’m trying to figure this out.

9

Okay, I was being lazy all weekend, but I’d like to get to work on this project now.

So, @murgero, we had a private conversation, and you said we should use Bookstack, and that you would be willing to host it? Could we look into trying out Bookstack?

10

I’ll setup one up tonight :slight_smile: I get out of work at about 6PM CST. So once I am home I’ll shoot you over a URL and we can get to work testing it out.

11

Cool. That is what us Arizonans call 5PM. Cya at 5PM!

12

Okay, so we did some work on the MIAB manual. @murgero is hosting it on his server, so please ask him to create you an account on his Bookstack if you wish to contribute to it.

That is not to say that we are trying to exclude anyone from the manual project, or make it proprietary. We have licensed our work under the creative commons license that MIAB is under, and I’ll try to keep an update version in PDF/TXT/HTML format on Github, just in case something happens to the data on murgero’s server.

Here’s the Github repository: https://github.com/EliterScripts/mail-in-a-box-manual

EDIT: Sorry if this upsets anyone, but I have created an IRC Freenode channel on Freenode.net (go to webchat.freenode.net if you’re new to IRC), which I found effective to communicate with murgero through. The channel’s name is #mailinabox-dev .

1 Like
13

Once we have the manual done, I can make bookstack sync with a github repo so this will be automatic in the future.

14

Hey, so I’ve done quite a bit of work on the manual, I’m currently working on the part of the manual where we talk about hosting, and choosing a hosting provider. I’ve started out with talking about self-hosting (physically), where you run your own datacenter (in our case, a datacenter of one server). There seems to be a lot I’ve wanted to talk about there, any ideas if that was too much or any of it being wrong?

Thanks!

15

I haven’t looked at it in a few days … I will take a look at it again later.

My initial thought on it was the self-hosting part was too long. My reasoning is that self-hosting is not a reasonable option for MiaB so it should not really be discussed in depth. It does have a purpose to be discussed though so I do not think that the topic should be overlooked completely.

On another note, I do think that we should have a place that those of us who are working on the project can collaborate. Bookstack will be a good medium for when it comes time to publish something per @murgero’s comments to me but it would be nice to have a place to kick thoughts and ideas around – I am not sure that this forum is the right place for that … maybe it is, dunno.

16

Etherpad coming up soon!

17

I mean, Mail-in-a-Box is focused on privacy and self-hosting, so I think it is worth mentioning that you don’t have to go to a VPS provider. I mean, hosting your own hardware does increase privacy and control over handing your mail server (physically) over to someone else. However, VPS does the job for the most part.

18

Yes, agreed … but I think more from the viewpoint of not having your emails read to subject you to advertising such as Google and others do as well as not having your email controlled by an entity which will hand over your data on request without even any advance warning. And, I cannot know what Josh’s thoughts on the subject of self-hosting were other than the assumption that he was referring to having YOUR OWN email set up vs someone else hosting it. I am making this assumption based on his comments on the MiaB homepage and the article which he referenced as being one of his reasons of inspiration.

Self-hosting as you’ve described it is simply beyond the scope of the masses for a couple of reasons usually out of the end users control.

  • The inability to have a static IP in many cases,
  • The inability to set a PTR (rDNS) record.

Most residential ISP’s will not provide a static IP address without some extra charge or service upgrade to a business class service. The same can be said about setting a PTR record. Additionally, many ISP’s block the necessary ports for email. So, going into it there are multiple issues.

19

Just some advice: Start with the most common use case (the one described in the setup guide) and get that one right before going on to more complicated use cases.

20

I agree wholeheartedly!