Server Manuals

I'm currently working on a SaaS project, hosted on a large cloud provider.
We're making headway with the project following the typical reasonable process of composing it of a combination of SaaS software development products' free tiers (like CircleCI) and numerous Open Source products and libraries like Python and nginx - not to mention the server OS itself which is an Ubuntu Linux.

As the project progresses, there more such systems are integrated into it.  While their developers in the great majority of cases are very scrupulous in making sure they're easily manageable, there are a number of ways to organize such management and they can differ quite widely.

Therefore it has become clear that a vital component of our work is to produce a Server Manual that details succinctly how to access, change and control each such system.  The production of the manual is motivated by the high likelihood of production issues in the future which will require intervention in real time to mitigate costly outages.

Organization

Given the motivation to avoid outages, it is necessary to consider worst-case scenarios.  One example is when the site goes down during a significant period of usage: therefore it is imperative to quickly bring it right to avoid losses - reputational and financial (due to missed sales) and possibly legal or other problems.

Further, it may be that due to time of day or other circumstances - employee vacations for example - the normal workstation administration environment is not available.  Perhaps only a smart-phone SSH interface terminal access is possible.  For this reason, the document must:

1. be text readable
2. be "small" - probably a few 100 KB maximum.
3. include all required information in one place: possibly more than one file, but so that there is no delay in getting all required information such as account ids etc
4. be succinct
5. easily and clearly readable

To obey these requirements a format like Markdown should probably be used.  Markdown is good because it is not bad for 1. above, and fine for 2.  It also renders on a browser nicely - which is important since in most cases that is how such manuals will be read.

Deployment

The manual has to be stored somewhere - and somewhere easily accessible.  For our purposes we see GitHub as a good choice: we create a new GitHub repo for each Manual.  The advantages are that we can set it up to be automatically deployed to the server(s) while having it remain easily accessible via the Web.

If you choose to follow these ideas, you should:

1. Go to github.com
2. Sign up to create an account.
3. Click the green New button to create a new repo.
4. Choose and enter a reasonable Repository name
5. Decide whether to make it Public or Private.  If public, be sure not to include any passwords or sensitive information.  It being public has the advantage of accessibility however.
6. It's a reasonable thing to use the initial README.md as the entry point (or perhaps the entire manual).  Therefore you can click the "Initialize this repository with a README" check-box
7. Create repository

You now have a repo with a README.  

Usage

For a relatively simple manual, you might start with just a single README.md.  You can edit this in place - just 

• go to your repo in a browser (something like https://github.com/yourname/your_repo_name), 
• look for README.md, click it then 
• click the edit iconat the top right of the file
• edit the doc in place 
• click Commit changes 
• the document is now available at https://github.com/yourname/your_repo_name/blob/master/README.md.

From the Server

The doc should also be deployed to the server itself.  To do that, on the server, make sure that git is installed and then do 

git clone https://github.com/yourname/your_repo_name.git 

which should create a directory called your_repo_name containing README.md.

You can include deployment of the repo in your server deployment scripts.

Offline

You may wish to work on the manual in your development environment.  For this you follow the same process of deploying the file to the server but this time to a local directory on your development box.  Markdown files are pure text, so you can edit with a text editor.  Many editors (like Vim, Emacs, VisualStudioCode, Sublime and PyCharm) come with Markdown plugins.  Also, there are various Markdown editors, for example Remarkable (though for Linux, Remarkable requires a little work).