Who is Responsible for Technical Documentation During Development

SOFTWARE DEVELOPMENT

Software Documentation: A Recipe for Success

As we dis­cov­ered in The Why and How of Software Documentation it is ex­ceed­ingly im­por­tant to doc­u­ment soft­ware de­vel­op­ment. We also dis­cussed where is the best place to doc­u­ment and con­tin­u­ously it­er­ate it. But who is re­spon­si­ble for the doc­u­men­ta­tion?

I guar­an­tee that if you asked vary­ing roles in the soft­ware in­dus­try, the re­sponse will dif­fer each time.

Types of doc­u­men­ta­tion

First and fore­most, it’s im­por­tant to iden­tify the dif­fer­ent types of doc­u­men­ta­tion that form part of a soft­ware pro­ject. Let’s split them up into two cat­e­gories:

  • the code­base and;
  • the sup­port­ing doc­u­men­ta­tion.

Theoretically speak­ing, as lines of code are writ­ten, there is a line of thought that says it’s al­ready doc­u­mented, be­cause “it’s right there in the code!” I have heard this line many times. In some cir­cum­stances, the code it­self is enough in­for­ma­tion for the de­vel­oper to de­rive what is hap­pen­ing. Other times, it falls short of what is needed.

The func­tion or script may have been writ­ten in a cer­tain way to en­sure some­thing does­n’t break in an­other part of the ap­pli­ca­tion. Without prop­erly com­mented code there is no way an­other de­vel­oper will know that it must work in that way.

A word cloud with 'Software Documentation' in the middle. Around the outside are icons for Adobe XD, jira, confluence, note taking, recordings and more.

One of the core el­e­ments of the ag­ile method­ol­ogy is that it is con­stantly learn­ing, with­out need­ing to start from the be­gin­ning each time. In doc­u­ment­ing the re­search, the tri­als and the suc­cesses, it means that the knowl­edge of not just how the soft­ware works but pre­sent­ing the dis­cov­ery as to why it op­er­ates the way it has been im­ple­mented, rounds out the un­der­stand­ing.

Project man­age­ment tools such as Jira ex­ist in the same suite as Confluence where they link to­gether seam­lessly, there­fore, pro­mot­ing con­sis­tent doc­u­men­ta­tion. Yet, even with seam­less in­te­gra­tions be­tween man­age­ment and con­text, the lack of doc­u­men­ta­tion for many soft­ware ap­pli­ca­tions is broadly felt by the in­dus­try.

Additionally, an ap­pli­ca­tion is not just made up of soft­ware. It is the col­lab­o­ra­tion of ideas and ex­e­cu­tion from prod­uct own­ers, de­sign­ers and de­vel­op­ers.

Product Owners, or the main busi­ness stake­hold­ers, have an im­por­tant con­tri­bu­tion to the soft­ware doc­u­men­ta­tion. They are able to cre­ate a back story, set the scene and pre­sent ex­am­ples for the prob­lem the soft­ware is aim­ing to solve. I have seen a bril­liant ex­am­ple of this from a re­cent cus­tomer of ours at WorkingMouse. The bril­liant ar­tic­u­la­tion of their busi­ness case, their user groups and their plan for the fu­ture of the ap­pli­ca­tion meant that every­one work­ing on this pro­ject was aligned on the ob­jec­tives.

This doc­u­men­ta­tion not only pro­vided us with a great un­der­stand­ing of the pro­ject from the be­gin­ning, but when we brought more de­vel­op­ers into the team, the on­board­ing rate was much faster than we an­tic­i­pated.

A quote block that reads "[Product Owners] are able to create a back story, set the scene and present examples for the problem the software is aiming to solve."

Who is re­spon­si­ble for soft­ware doc­u­men­ta­tion?

As some­one who has worked with a range of dif­fer­ent de­vel­op­ment teams, I have never re­ally come across a valid rea­son for why this re­spon­si­bil­ity seems to bounce around from team mem­ber to team mem­ber.

As I’m not a soft­ware en­gi­neer, and I feel like I have said the word “code” too many times al­ready, I am go­ing to put this sit­u­a­tion into a more re­lat­able sce­nario. One of my pas­sions is cook­ing and one of my hob­bies is pour­ing over cook­books. Something I no­ticed about the recipes that I tend to lean to­wards, for in­spi­ra­tion or to fol­low, are the ones that have a lit­tle blurb at the top of them writ­ten by the au­thor chef.

I know this is a strange com­par­i­son be­tween tech­ni­cal doc­u­men­ta­tion and cook­ing but stay with me!

Each time I read a blurb about a recipe, I am im­me­di­ately ori­ented with the style I need to be cook­ing in and the kinds of re­sults I should see in the end. Therefore, when I get into cook­ing the recipe that con­tex­tual in­for­ma­tion is sub­con­sciously guid­ing my ac­tions and (hopefully!) I get the re­sults in­tended. Something par­tic­u­larly in­ter­est­ing with this ap­proach is the abil­ity for some­one who is not an avid cook to read the blurb and then be able to cre­ate their own un­der­stand­ing of what they might eat (or at­tempt to cook!).

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

We can think about this style of in­for­ma­tion trans­fer be­tween an ex­pert and an en­thu­si­ast sim­i­lar to a soft­ware en­gi­neer and a prod­uct owner. The soft­ware en­gi­neer de­vel­ops the recipe for the prod­uct owner to read, but the steps alone don’t paint a pic­ture of what the recipe is for or what it is in­tended to cre­ate in the end. Hence, the blurb.

The other style of knowl­edge trans­fer we need to con­sider here is the soft­ware en­gi­neer who cre­ated the ap­pli­ca­tion, to the soft­ware de­vel­oper who is go­ing to main­tain or it­er­ate on it. Most of the time you’re not doc­u­ment­ing for your­self, you’re doc­u­ment­ing for Developer Z that en­ters the pro­ject 12 months later with no back­ground con­text. What do they need to know to suc­ceed in their role?

To fol­low our kitchen metaphor, think of an ex­ec­u­tive chef en­trust­ing their care­fully cu­rated recipes to their un­der­ling chefs. It is the trust that the kitchen staff will be able to re­pro­duce that recipe time and time again to the stan­dard the ex­ec­u­tive chef first cre­ated it.

Honestly, this just sounds like a very nor­mal part of #cheflife but as some­one who has worked with chefs, I can tell you that they re­ceive those recipes with notes and con­text and a show­case of how to cook them. It is this care­ful trans­fer of knowl­edge that al­lows the chefs to suc­ceed.

So, what can we draw from this metaphor? This brings me back to one of the first points I raised in this piece, the fact that the re­spon­si­bil­ity of soft­ware doc­u­men­ta­tion is not agreed upon. The re­spon­si­bil­ity of cre­at­ing the doc­u­men­ta­tion lies with the cre­ator.

Document now, ben­e­fit later

Have you ever looked at some­thing, like a bill­board or poster and won­dered, “why is that de­signed in that way?” I can ab­solutely tell you now, that al­though the de­sign may seem sim­ple, there would have been hours ded­i­cated specif­i­cally to it. During those hours, there would have been moun­tains of re­search un­der­taken and many de­ci­sions made. The same goes for the de­sign of an ap­pli­ca­tion. Product de­sign­ers com­mit hours to un­der­stand the user and de­sign­ing a sys­tem that will suit them per­fectly. This user un­der­stand­ing should be doc­u­mented also for the same rea­sons as I have fleshed out above. It pro­motes con­sis­tency, and con­ti­nu­ity of the ap­pli­ca­tion.

It is a part of WorkingMouse’s Way of Working that we al­lo­cate time to doc­u­ment every­thing through­out a pro­ject. It is also con­sid­ered ready for com­ple­tion when every­thing has been doc­u­mented suc­cinctly so an­other de­vel­oper, a non-tech­ni­cal per­son and even the prod­uct owner can re­view and un­der­stand what has been writ­ten.

Discover Software
Secrets

ABOUT THE AUTHOR

Alice Spies

KPI mo­ti­va­tor and res­i­dent head chef

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

What is Agile Software Development: How to Start with a Problem

16 October 2020

The Advantages of Agile Project Management

09 September 2020

What’s the Best Agile Project Management Method For You: Scrum vs Kanban

11 September 2020

Your vi­sion,

our ex­per­tise

Book a con­sul­ta­tion