Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question
2  
Reduce the multi-step procedures to a single command: a build target or script or shell function or whatever. Each developer action should be doable with a single command. The developers will be more likely to keep the scripts working than they will be to update documentation. –  kevin cline Sep 6 '12 at 17:35
    
Thanks kevin. it is also easier to use variables in a shell script than in documentation. –  UmNyobe Sep 7 '12 at 7:16
add comment

2 Answers 2

up vote 4 down vote accepted

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.