Wednesday, June 8, 2011

Aspergers/ASD and Agile software development: Part Three - Documentation

Part three (read Part 2 here) of my series on Aspergers/ASD and Agile Software Development addresses the Agile principle of valuing Working Software over Comprehensive Documentation. In many ways I see this principle as exposing many deficiencies in the software development process as a whole: the misuse of developers as document writers; the overblown documentation that is so pervasive in older development houses; and the antipathy of many developers to document anything (including comments in the code).

I believe that the attachment to documentation by ASD folk comes more from wanting to know what is expected of them and the software as well as the difficulties that verbal communication presents (overwhelming information; unwanted stimulation; eye contact) than a love of documentation for documentation's sake. Keeping this in mind I offer the following pieces of advice:


  1. The principle stresses 'comprehensive' documentation but does not totally eliminate the need for some documentation. When interviewing ask what their opinion of 'comprehensive' is and ask for examples. If it is enough for you to get started and puts you in a position that you can learn more about the system then it is probably a good situation. If however they have no documentation or one line documentation (e.g. "add no-balance accounts to processing") run. That is bad practice in ANY development methodology.
  2. Use the documentation to launch yourself into a knowledge hunt. Teasing out the information needed can be fun and rewarding in and of itself. Remind them and yourself that their chosen methodology makes this a necessity.
  3. Broaden your definition of documentation. I often use server logs, the code base itself, SQL Trace functionality and watching users operate as 'documentation'. In many ways it is more honest than user manuals and product specs as they show exactly how the software operates and not how someone thinks or perceives it should work.
  4. Create your own documentation. With the advent of phone based cameras, easy screen capture methods and self publishing tools you can create your own documentation for your use. Who knows, you might even be able to hand it off to a fellow Aspie and make their day.
Going to a loose methodology like Agile can be difficult but it should not keep you from working at a place as long as they follow some basic rules. There is always a need for documentation just make sure it is reasonable. I once worked in a place where I filled out a project document that was 50+ pages long... and I edited 7 pages for a total of 20 lines. Way too much boilerplate information there. On the flip side the one sentence product spec is a recipe for disaster. Find what works for you.

3 comments:

  1. Also PLEASE ensure your apps produce logfiles that are useful to support people when resolving issues - especially when it comes to authentication with other systems - so a helpdesk person can pass an accoutn reset to security teams without hassling devs..

    I have 21 years in IT support - not dev... so I see it from the other side..

    ReplyDelete
  2. Agile software development I think this is an informative post and it is very useful and knowledgeable. therefore, I would like to thank you for the efforts you have made in writing this article.

    ReplyDelete
  3. Thanks for taking the time to discuss this, I feel strongly about it and love learning more on this topic. If possible, as you gain expertise, would you mind updating your blog with extra information? It is extremely helpful for me. Offshore development services

    ReplyDelete