A Culture of Documentation

I have been brewing this thought over the last week six months or so… what if we could build in developers a culture of documentation. The reason I have been having this thought is because it is the thing that developers hate to do and yet the thing that other developers most need.

I used to work in a great company (it was aquired by IBM) that employed a really good technical writer to do all the help for the users, the training material and other outputs that the company needed.

That is all well and good but developers should take responsibility of their own documentation. I am not suggesting that they should have the scope of documentation that this technical writer did but there is room for improvement in most cases.

This starts with self-documenting code. Use of standard and consistant naming conventions across the codebase will mean that developers will be able to recognise what is going on more easily, especially if the variables are named with meaningful variable names.

Secondly, the code should be well commented. This should include a flower-box or equivalent for your language at the top of the file to describe the purpose of the file. Hopefully this will be able to be parsed by some automatic documenting tool like javaDoc or PhpDoc to generate documentation for the project.

Thirdly there should must be some source control. If you are in a development team of greater that zero then you must use source control. I have been using subversion for projects I have been working on for over a year now and there is no way that I would go back. Even if the project I was working on was a personal project. If you don’t want to go to the bother of setting up a subversion server of your own then use google’s new code service.

Fourthly, use a wiki. Wiki’s are a great way to easily capture documentation that can be shared with your developement team. It’s easy to create a heirarchy of pages that can be navigated or bookmarked for future reference. I find this particularly useful for tasks that I do regularly but not often enough to remember how they work. I can quickly check customised version of command that I need to issue or screenshots to check that I am on the right track.

Lastly, and I am thinking of SAP here, if there is scope in your development platform for capturing documentation, then capure it. There are lots of places for capturing documentation in an SAP project. All custom dictionary objects can be documented, all reports can be documented, all classes can be documented… need I go on? What can be a tad annoying with SAP is finding that there is no documentation in these standard places for SAP delivered objects.

No documentation available

Lets reverse this trend and employ a culture of documentation. What are your thoughts? How can we get developers to realise the importance of documentation? and then actually DO it?

Technorati Tags: , , , , , , , ,


7 Responses to “A Culture of Documentation”

  1. 1 Michael Koch Thursday, 15 February 2007 at 8:50

    As far as SAP documentation is concerned, I’ve had quite a few occasions where the message actually said “No documentation available in language EN.”, which prompted some of my colleagues to come to me and say, “Hey, Michael, can you sign on in German and let us know what this Function Module (etc) actually does?”.

    But no such luck, my friends “Keine Dokumentation in Sprache DE verfuegbar.”. Why should I be any better off? 🙂

    Another thing I also noticed is that it is always beneficial to read SAPNotes in both English and German. On far more than just one occasion I was surprised how much clearer (and often more detailed) the German version was. But obviously not everyone has this option…

  2. 2 ilya Thursday, 15 February 2007 at 19:54

    After long years, nothing can now change my mind that it’s in its own interest of SAP to don’t provide good technical documentation. Even relatively-well documented BAPIs need much more explanations. There’s kind of a small revolt on the Web, however, called se37. You may want to give it a try. Today it doesn’t provide much more content than an SAP system, but the main difference is a fully searchable index and possibility for others to create documentation.

  3. 3 theotherthomasotter Thursday, 15 February 2007 at 21:40

    just to really ttcatp (throw the cat amongst the pigeons)

    Read the Amazon CTO’s personal view…

  4. 4 nigeljames Friday, 16 February 2007 at 10:26

    Thanks Ilya and Thomas. Great Links.

    Can we have some of those hungry cats to clean up Trafalgar Square please?

  5. 5 Oliver Monday, 19 February 2007 at 14:05

    Just think about if SAP would have cared about documentation for all their function modules, dictionary objects and classes from the very beginning, it would have saved so much time for so many developers. Every developer who has done some serious work with an ABAP based SAP system knows about the deep integration of all components via DDIC and the resulting compile time checks. It’s way supperior in this respect to anything I’ve worked with but documentation still lacks. Finding the right funtion module can turn out into a nightmare.

    Maybe it’s time for a community approach. I like the idea behind se37 (the site) but wouldn’t SDN be a better place for it? I have a dream where all dictionary objects, all function modules for all solutions (R/3, CRM, SRM, etc.) are well documented for each release and of course indexed and searchable from SDN…way to go.

    Btw. the Java side is only slightly better.

  6. 6 Martin Wednesday, 14 March 2007 at 17:38

    You guys are absolutely right about one thing: Documentation is not SAP’s forte. That they have managed to get where they are in the marketplace is nothing short of a wonder. (Internally, the documentation might be good; I wonder how the competition stacks up?)
    There is something inborn about developers though, in that they like to figure out how things work. So if there is no documentation, they will sit with something and work at it until they have figured it out. I wonder if SAP knows this and has been playing us all these years.
    As for the rest of us: we need to train the cleaning staff that come into the office at night and empty the dustbins and vacuum the carpets to also log on to our systems and document the code we wrote during the day. That way, when we arrive the next morning, everything is in order.
    When you say “culture”, Nigel, it sort of evokes keywords for me such as “responsibility”, “accountability”. Like a testing team that ensures everything coded is working as advertised, there should also be a team that checks whether everything has been documented. But that task is beneath a developer, I’m afraid 🙂

  7. 7 Martin Friday, 16 March 2007 at 8:11

    Actually, there was something else I meant to say: the SAP ABAP stack has great built-in features for documenting repository objects, which you mentioned, Nigel. It’s a great shame that it doesn’t get used to its intended extent. If you could encourage developers to use that, then half the battle is won. The key is discipline, and I would like to reiterate the need for accountability. Developers in a team should be accountable to each other, and checking each other’s documentation, even if they don’t check each other’s coding.

Comments are currently closed.

%d bloggers like this: