Agile, Continuous Integration and Software Documentation

At an event hosted by the Electronics KTN and DSP Valley I had a conversation with the CEO of Easics NV about the suitability of the Agile methodology for embedded software development. One thing we agree works well is the use of Continuous Integration.

For anyone unfamiliar with the concept, Continuous Integration is a software development practice that requires regular and frequent (e.g. daily) check-in of new code. It requires a code repository with minimal branching, and the evolving repository (aka "top of tree") should be built and tested on an equally regular basis.

One impact on software team resource planning is that it is a very good idea to include tasks that make the build self-testing and reporting tools for informing the rest of the team about the results of those tests. There are tools available that can help.

It calls for integration into the daily project plan of each developer. For example, if yesterday's check-in broke the overnight build, then today's first priority is to fix it. That way, all other team members can continually integrate and test their changes against the incremental build.

The #1 benefit is that it saves surprises and unplanned effort during the software integration phase, which in the traditional software waterfall method comes late in the development cycle. But it also fits well with other elements of the Agile method, such as using short, focused user stories as the means of capturing requirements, and the fast turnaround of feature development associated with Scrum.

Book a free demo of the Cognidox Document Management System

There are other areas of Agile less compatible with Embedded Software, at least as it applies to the Electronics industry. There is nothing in Agile that formally opposes system documentation, but many proponents de-emphasize it. This may be fine for e.g. website development, but writing the software sections of a Silicon Specification document is not optional in chip development. It's also not obvious how you would express a DSP algorithm requirement in terms of a user story.

The way some "Agilists" talk about documentation is illuminating, for example:

"The economic difficulties of the past months have finally put waterfall out of its misery; now more than ever, long requirements phases and vaporous up-front documentation aren't acceptable" - Cennydd Bowles

"Friends build products; enemies only build documents" - Steve Johnson

As I say above, there is nothing intrinsic in Agile that means documentation isn't important, but when the emphasis is on co-located teams, requirements analysis by card sorting and the prototyping of working code; it isn't a major surprise that documentation can be downgraded.

Interestingly, the technical writers that I've spoken to about this are not especially big on Agile - they seem far more interested in modularity and the re-use of structured XML components than they are in the methodology of production.

Generally, documentation is still the bane of software development. Jerry Weinberg summed it up in 1971:

"Documentation is the castor oil of programming. Managers think it is good for programmers, and programmers hate it". There is still a tendency to try to avoid doing it.

Sometimes, a Wiki can be used to assist the software development team. This tends to be better at the "how" of software production rather than the "why". For example, a Wiki describing how to run the automated test build will probably be well-used and maintained. Documentation about the user commands and error conditions has a lower probability of maintenance.

The way around this is to go with the psychology of the programmer - their locus of attention will be on the code and the aim should be to make the documentation fit around that. An ideal version of this might be the idea of Literate Programming proposed by Don Knuth in the 1980s. The output of the developer's labour is a composite of executable code and (human) documentation.

The next step is then to ‘harvest' this documentation so that it can be presented in the formats that humans prefer - user guides, quick start manuals, on-line help, etc.

There are a few interesting examples of tools that try to achieve this. For example, Doxygen is an open source tool that will extract help text and APIs from source code (C, C++, Java, many other languages) and auto-generate documentation from it in HTML, PDF, RTF, LaTeX, and other formats. In teams I've worked with, it was used to document an embedded RTOS and a device driver framework. It seemed to work well for that purpose, but it required a conscious decision to use it as part of the coding. I've never seen it used for end-user documentation, and am unable to say how well it might work.

Another example is the Publican tool that Red Hat made available as open source. This has the right idea - taking XML and turning it into HTML and PDF with style sheets, but it is complex to learn and is specific to Red Hat's DocBook.

I've read that Microsoft Sandcastle is a similar documentation generator that automatically produces MSDN style documentation from .NET development. However, I have never seen it used in software development so can't really comment.

The conclusion I feel is that there is still considerable room for improvement in this area.