The Why and How of Software Documentation


When start­ing a soft­ware de­vel­op­ment pro­ject, one of the most im­por­tant con­sid­er­a­tions to make is how you will doc­u­ment the de­tails of the soft­ware you are build­ing. You may not re­alise it at the time but think about this sce­nario. You en­gage a soft­ware com­pany. At first it goes well. But you soon re­alise they lack the ex­per­tise or the processes to de­liver your pro­ject the way they ini­tially promised. It’s some­thing we’ve seen hap­pen again and again. A new en­quiry comes through af­ter a bad ex­pe­ri­ence and we try to save the pro­ject. But in­stead of look­ing through a well doc­u­mented ap­pli­ca­tion, we must de­ci­pher the source code to un­der­stand the orig­i­nal de­vel­op­ers in­ten­tions (which can be dif­fi­cult at the best of times).

Why is soft­ware doc­u­men­ta­tion so im­por­tant?

When start­ing a new soft­ware pro­ject, it is crit­i­cal to the long term suc­cess to en­sure you are dili­gently doc­u­ment­ing as much in­for­ma­tion as pos­si­ble through­out the process. Think of this in­for­ma­tion as the man­ual to your soft­ware that should en­able an­other per­son to pick up where oth­ers have left off and con­tinue work­ing.

The pri­mary pur­pose be­hind doc­u­men­ta­tion is en­sur­ing con­ti­nu­ity. See our ex­am­ple above for ref­er­ence. You do not want your new de­vel­op­ers to have to ded­i­cate a sig­nif­i­cant amount of time re­verse en­gi­neer­ing the de­ci­sions made when ini­tially de­vel­op­ing the soft­ware so they can un­der­stand how the sys­tem works. This time and money has to be ded­i­cated to just un­der­stand­ing what and why the soft­ware func­tions in the way it does, all due to poor doc­u­men­ta­tion of the prod­uct when it was be­ing built. This will de­lay the time be­fore the new de­vel­op­ers can even start work­ing on the prod­uct to ex­tend its ca­pa­bil­i­ties.

If the doc­u­men­ta­tion were a fo­cus both be­fore and dur­ing de­vel­op­ment, the bur­den on the new de­vel­op­ers could be re­duced. They would be able to study the ex­ist­ing doc­u­men­ta­tion to get up to speed on how they sys­tem func­tioned, rather than re­verse en­gi­neer­ing it, re­duc­ing the time be­fore they can con­tinue de­vel­op­ing the plat­form. This same sce­nario is ap­plic­a­ble even if you have in­ter­nal de­vel­op­ers. In an ag­ile soft­ware pro­ject it’s so crit­i­cal to keep mo­men­tum up. This is lost when try­ing to de­ci­pher your soft­ware.

What should you doc­u­ment?

When be­gin­ning a soft­ware pro­ject, there are three types of com­mu­ni­ca­tion that oc­cur to make up the arte­facts re­quired for a soft­ware de­vel­op­ment pro­ject: lan­guage, text and pic­tures. It is im­por­tant to doc­u­ment as much of this ini­tial dis­cov­ery process as pos­si­ble, be that by record­ing the meet­ings you have (language), writ­ing notes and doc­u­ment­ing why de­ci­sions are made (text), and take pho­tos or screen­shots (pictures) of any kind of mind map­ping, white­board­ing or di­a­gram­ming you and your team may do. Ensuring you are record­ing this in­for­ma­tion from the be­gin­ning of the process sets you up for suc­cess as you con­tinue down the path of soft­ware de­vel­op­ment. The key piece of doc­u­men­ta­tion to en­sure is cre­ated at this point is the busi­ness case for de­vel­op­ing the soft­ware. Having this en­sures the busi­nesses de­ci­sion for cre­at­ing this soft­ware is clearly ar­tic­u­lated.

When mov­ing into the scop­ing phase of a pro­ject, doc­u­men­ta­tion is even more cru­cial. It is at this point where sev­eral very im­por­tant de­sign and tech­ni­cal de­ci­sions will be made, and it is im­por­tant to have all of these de­ci­sions clearly ar­tic­u­lated. At WorkingMouse, some of the arte­facts we pro­duce and doc­u­ment in­clude but are not lim­ited to:

  • The en­tity di­a­gram of the ap­pli­ca­tion (database schema),
  • Backlog of re­quire­ments in­clud­ing both Epics and User Stories,
  • Prototypes and key de­sign de­ci­sions made,
  • User in­ter­views and feed­back,
  • Any ma­jor se­cu­rity or tech­ni­cal de­ci­sions made,
  • Estimations spread­sheet,
  • Ticket pri­ori­ti­sa­tion.

The next phase in the de­vel­op­ment cy­cle is to start cod­ing the soft­ware. At this point, it is per­ti­nent to en­sure your de­vel­op­ers are dili­gently com­ment­ing their code and doc­u­ment­ing any ma­jor tech­ni­cal de­ci­sions they make. At WorkingMouse, we bake this time into our es­ti­ma­tions, called Iteration N, to en­sure our de­vel­op­ers have an ad­e­quate amount of time dur­ing de­vel­op­ment to doc­u­ment their code and clean it up. This time in Iteration N en­sures the code­base and doc­u­men­ta­tion is ready for other de­vel­op­ers within WorkingMouse or our sup­port team to pick up.

Lastly, once de­vel­op­ment of your soft­ware has fin­ished, it will be passed on to a team to sup­port the ap­pli­ca­tion. When sup­port­ing an ap­pli­ca­tion, the team will make many de­ci­sions about the de­ploy­ment of the ap­pli­ca­tion and any bug fixes they make. It is per­ti­nent all this in­for­ma­tion is in­cluded in the doc­u­men­ta­tion of your soft­ware.

Where should you doc­u­ment your soft­ware?

As you can see, there is a lot of in­for­ma­tion that should be doc­u­mented when de­vel­op­ing a piece of soft­ware and the last trap you want to avoid falling in to is hav­ing this in­for­ma­tion stored in a num­ber of dis­parate lo­ca­tions. Having a cen­tralised place to store all your doc­u­men­ta­tion is crit­i­cal, as with­out know­ing where all your doc­u­men­ta­tion is stored, you may as well not have writ­ten it. At WorkingMouse, we use two ma­jor soft­ware pack­ages to store our doc­u­men­ta­tion de­pend­ing on the needs of the client, the Atlassian suite of prod­ucts and Codebots.

The Atlassian suite con­tains a num­ber of prod­ucts for sup­port­ing soft­ware de­vel­op­ment, pro­ject man­age­ment and con­tent man­age­ment. The two key prod­ucts we use are Jira and Confluence. Jira helps plan, track and man­age soft­ware de­vel­op­ment pro­jects by pro­vid­ing tools to track tick­ets, bug fixes, time spent on a pro­ject and the back­log of a pro­ject along with sev­eral other fea­tures. Confluence on the other hand is a knowl­edge base, where more gen­eral in­for­ma­tion on the pro­ject can be stored in a cen­tralised repos­i­tory such as pro­ject arte­facts. Both Confluence and Jira con­nect with one an­other, al­low­ing seam­less in­for­ma­tion shar­ing be­tween both prod­ucts.

The Codebots plat­form also looks to cen­tralise the doc­u­men­ta­tion of a soft­ware de­vel­op­ment pro­ject in one place. The Codebots Library acts as the knowl­edge base for all arte­facts, sim­i­lar to Confluence, as well as doc­u­men­ta­tion of any code writ­ten by the bots (and hu­mans) known as the ref­er­ence im­ple­men­ta­tion. The plan­ning sec­tion en­ables the team to map out the back­log of re­quire­ments and tick­ets they are work­ing on as part of the pro­ject. Further, the Codebots plat­form also stores vi­tal in­for­ma­tion such as the en­tity di­a­gram and se­cu­rity ma­trix.

Regardless of the soft­ware pack­age you use to doc­u­ment your soft­ware, what is most im­por­tant is that you are dili­gent with record­ing as much in­for­ma­tion as pos­si­ble and cen­tralise the place in which you store that in­for­ma­tion. This en­sures that the tran­si­tion of your soft­ware pro­ject to a new team of de­vel­op­ers or for han­dover to sup­port is as pain­less as pos­si­ble.

Discover Software


Oliver Armstrong

Get cu­rated con­tent on soft­ware de­vel­op­ment, straight to your in­box.

Your vi­sion,

our ex­per­tise

Book a con­sul­ta­tion