How to correctly write an installation or setup document
- by UmNyobe
I just joined a small start-up as a software engineer after graduation. The start-up is 4 year old, and I am working with the CEO and the COO, even if there are some people abroad. Basically they both used to do almost everything. I am currently on some kind of training phase. I have at my disposition architecture, setup and installation internal documentation. Architecture documentation is like a bible and should contain complete information. The rest are used to give directions in different processes.
The issue is that these documents are more or less dated, as they just didn't have the time to change them. I will be in charge of training the next hires, and updating these documents is part of my training. In some there is a lot of hard-coded information like:
Install this_module_which_still_exists
cd this_dir_name_changed
cp this_file_name_changed other_dir_name_changed
./config_script.sh
./execute_script.sh
The issues i have faced :
Either the module installation is completely different (for instance now there is an rpm, or a different OS)
Either names changed, and i need to switch old names by new names
Description of the purpose of the current step missing.
Information about a whole topic is missing
Fortunately these guys are around and I get all the information I want and all the explanations I need. I want to bring a design to the next documents so in the future people don't feel like they are completely rewriting a document each time they are updating it.
Do you have suggestions?
If there is a lightweight design methodology available online you can point me to it's nice too.
One thing I will do for sure is set up a versioning repository for the documents alone. There is already one for the source code so I don't know why internal documents deserve a different treatment.
