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.
2
Technically, I think a decent wiki platform is the best choice for most of this sort of documentation. Easy to get at, easy to fill in, good search and version history are all great features for this task. Exactly which platform isn’t important — I’d run with whatever is in place first.
The best advice I’ve heard on this sort of thing is that the most experienced people in the shop should write it, and the least experienced people in the shop should test it so you can find what the team leads skip over.
Well, I think the real issue is that you want your installation document to be kept up-to-date. That is nothing you can really solve by improving the design of the document. Someone has to be responsible for this, for example, the developers of the system whenever they change something which influences the installation.
Of course, the chances that someone takes care of this are much higher when the installation description is very small, so what @kevincline wrote in his comment is a step in the right direction: create scripts or installer procedures requiring as few user interaction as possible. A simple “readme” file should be enough – ideally, you don’t need any installation description, because you just start your “setup” script which does all the right things.
However, if you move installation description into installation scripts, then still those scripts have to be kept up-to-date, which in fact only shifts the problem from one media to another. Someone has actually to test those installation scripts on a regular basis, and fix issues as soon as they occur. Of course, having just one installation script for a program has the advantage that the installation can be tested with much less manual effort.