From Kees van den Broek. May 22, 2010, 1 Comment

The traditional approach to documentation in a technical company is setting up a wiki on the intranet.

In my experience, it’s not a good enough solution, because of these issues:

1. A pain to maintain properly, i.e. extra ACL administration.
2. A wiki comes with a default markup language, and it needs to appeal to all who work with it.
3. If it ain’t time efficient for programmers, they’ll not use it.
4. Content should be easy to migrate when a wiki sytem is no longer maintained or fitting the organisation.
5. Attachments (i.e. flowchart images) are rarely in sync with reality, it’s too much effort to update.

Let’s take a step back and look at the fundamental question: where should documentation go?

If possible, ‘documentation’ should be the code itself. Whenever there’s more to explain, it should be in comments around the actual code. Meta-documentation for a specific project should go in the projects README (i.e. setting up the test environment).

Documentation on setting up an IDE that’s applicable to multiple projects should go in a more generic place outside any specific project.
‘Getting started’ documentation for new interns (codingstyle, traps to avoid, etc.) also needs a place.

There is a ’simple’ solution to the problem, although it requires a little bit of scripting. The benefits:

1. Integrates well into the workflow of programmers
   - put project-related documentation close to the actual code.
   - use any editor, any markup language. (example script supports only markdown)
   - documentation is in textfiles, in your regular VCS. (in our case Subversion)
   - create a link to a specific source file or diagram by using a VCS relative path. No more uploading of binaries to the wiki.
2. No extra system administration needed
   - ACLs and older revisions are provided by the VCS

This is the ‘architecture’ overview, compared to a traditional wiki. Two very small shell scripts is all there is to it.

This is how the ‘Getting started with Android’ page for new interns looks:

Scripts can be downloaded below.

What’s your ideal solution?

The above rendering was generated from this documentation snippet:

Android SDK (optional)
----------------------
 
Download the Android SDK R06 from [](http://developer.android.com/sdk)
 
~~~ {.bash .numberLines}
cd $ECLIPSE_BASE
tar xvfz ~/Downloads/android-sdk_r*-linux_86.tgz
# Add to .bashrc (the escaping backslash is intended)
cat << EOF >> ~/.bashrc
export PATH=\${PATH}:$ECLIPSE_BASE/android-sdk-linux/tools
EOF
~~~

That’s a bit of ‘markdown’, including support the the ‘markdown extra’ specification.

Before render.sh renders HTML from markdown, the preprocessor.sh script runs a few regexes.

This adds some flexibility to our documentation. It allows to define our SVN hostname globally (it may change one day, and many documentation pages are affected).
So when we refer to our repository from documentation, this is how it’s documented:

# Create new repository location -> ___DC_REPOS___/trunk/src/project_x

And this is what’s in the final HTML:

# Create new repository location -> svn+ssh://svn.kvdb.net/svn/trunk/src/project_x

Another useful substitution is showing a picture that’s located inside the repository.

![Architecture of project x](___ROOT___/trunk/src/project_x/diagram.png)

___ROOT___ will be replaced with the path to the webdav view of the repository (content is still protected using webdav ACLs):

<img src="http://svn.kvdb.net/trunk/wiki/wiki.png" alt="Wiki architecture"/><p class="caption">Wiki architecture</p>

We use a Subversion hook to keep a current view of the documentation on the intranet (see below) whenever a developer checks in new documentation.
Without further ado, here are the scripts:

Put this script (+x) in YOUR_REPOSITORY/hooks/post-commit:

#!/bin/sh
 
REPOS="$1"
REV="$2"
 
# Export the repo
DEST=/tmp/svn_wiki_gen
# Checkout or update the whole SVN repos.
if [ -d $DEST ]; then
  svn up -r $REV $DEST
else
  svn co -r $REV "file://$REPOS"/trunk $DEST
fi
 
# Gather all documentation and create wiki
cd $DEST/wiki
./render.sh

This is render.sh:

#!/bin/bash
 
# Drop generated HTML pages here
OUTPUT_DIR=/home/kvdb/public_html/wiki
# Where should we start gathering input
INPUT_DIR=/tmp/svn_gen_wiki/
# Where to put a temporary file
TEMP_DIR=/tmp
 
# Make sure output path exists
mkdir -p $OUTPUT_DIR
 
source $INPUT_DIR/wiki/preprocessor.sh
 
# Apply some basic styling to the generated output
# See: http://www.blueprintcss.org/
STYLE="-c blueprint/print.css -c blueprint/screen.css"
cp -R blueprint $OUTPUT_DIR
 
files=`find $INPUT_DIR -regex ".*\(mkd\|mkdown\)$"`
for file in $files
do
    filename=`basename $file`
    all_but_extension=`echo ${filename/.*/}`
    # Run preprocessor, substituting strings (output to /tmp/preproc)
    preprocess ${file} $TEMP_DIR/preproc
    pandoc $STYLE -f markdown -t html $TEMP_DIR/preproc > $OUTPUT_DIR/${all_but_extension}.html
done

This is preprocessor.sh:

#!/bin/bash
 
function preprocess {
    source_file=$1
    dest_file=$2
    echo Preprocessing: $source_file
    cp $source_file $dest_file
    sed -i "s/___DC_REPOS___/svn+ssh:\/\/svn.kvdb.net\/svn/" $dest_file
    # The webdav path
    sed -i "s/___ROOT___/http:\/\/svn\.kvdb\.net\/svn\/trunk/" $dest_file
    # Process file local substitutions
}

One Response to “A developers approach to documentation”

1. JACOB says:

   September 8, 2010 at 6:45 pm

   
   

   CheapTabletsOnline.com. Canadian Health&Care.No prescription online pharmacy.Best quality drugs.Special Internet Prices. No prescription drugs. Buy drugs online…

   Buy:Benicar.Ventolin.Amoxicillin.Female Pink Viagra.Zocor.Lipothin.SleepWell.Wellbutrin SR.Seroquel.Zetia.Advair.Cozaar.Lipitor.Prozac.Aricept.Buspar.Female Cialis.Acomplia.Lasix.Nymphomax….