Documentation for Academic Developers

Feb 28, 2011 by ananelson

This is a guest post by Ana Nelson.

As an open source software developer with an academic background, it was my very great pleasure to be introduced to the DevCSI project and the community it supports recently at Dev8D 2011. I’m the author of an open source package called Dexy which hopes to change the way developers document software, and I had the opportunity at Dev8D to introduce people to Dexy and to learn about some of the particular issues facing academic developers when it comes to documentation. I am delighted to say that as a result, I am working with Mahendra to plan some upcoming developer documentation events which we hope will bring significant benefits to developers as well as the projects they are working on.

On Wednesday at Dev8D, there was a very interesting panel discussion about issues relating to documentation. For some developers, documentation is an unpleasant and distracting task, taking them away from the programming they’d rather be doing. For others, it’s something they’d like to do more of if they could only find the time. Some felt that readable code and code comments were all that should be needed. For a passionate few, writing documentation is a core part of their programming workflow. My co-panelist Stephanie Taylor talked about her perspective as someone whose job was to try to ensure that reluctant programmers did write documentation. We also heard from some developers who want to write documentation but whose bosses didn’t see that as important enough to take the time to do it.

Most agreed that documentation was an important part of any software project, and that very few projects have enough of it. I mentioned the strategic importance of documentation to a project, documentation being an important way for other people to find out about and start using an open source project, thereby spreading the benefits of that work to a wider audience. The intrinsic benefits of documentation, such as greater efficiency when you have documented things like installation routines for yourself so you don’t have to recreate them from scratch each time, and the beneficial effects on code quality which come from the reflection brought about by the process of writing, were also discussed.

After lunch on Wednesday I gave a lightning talk about Dexy, in which I showed several examples of documents prepared with Dexy. A PDF installation guide based on a real install script, the Dexy newspaper – an actual tabloid-size newspaper written in LaTeX with many code examples, an example of developer documentation for a web application including screenshots which were backed by functional tests, and even business cards!

On the Thursday of Dev8D, we held a “Getting Started with Dexy” workshop where people got Dexy installed and running on their laptops and were able to work through some of the tutorials, with help available should they have questions or run into problems.

After these events and the discussions I had with several developers, I thought more about how to start to address some of these issues. The lack of good tools for writing documentation is, I feel, a huge piece of the puzzle. There are many excellent tools for specific types of documentation, in particular many object-oriented languages have built-in tools for writing API reference documentation (e.g. JavaDocs, RDoc, pydoc), however these tools are very specialized and don’t tend to work well for other types of documentation, such as tutorials, nor do they deal well with the fact that projects these days almost always involve more than one programming language (it would be hard to find a project that didn’t include, at minimum, a few bash scripts or some JavaScript). Dexy lets you continue to use specialized tools for some parts of your documentation, and also gives you the flexibility to write other types of documentation in different formats (tutorials, user guides, lecture notes, presentation slides, posters, even blog posts).

Other tools such as using wikis or word processors for writing documentation allow more flexibility to write different kinds of documents, but these have the drawbacks of not being literate, that is, not relating to live code. Including code by copy-and-paste is cumbersome and, of course, not easily maintainable as the code changes. These types of tools also reinforce a sense that writing documentation is “not programming”. At least building JavaDocs feels like compiling code. With Dexy, you can write literate documentation using command line tools and with your favourite text editor, so it’s stress-free and doesn’t involve a big switch from your usual working environment.

In addition to tooling, there is the question of time. It is hard to take time out of everyday development work to write documentation, regardless of how much support there is from above for this activity. And, if there is an anticipation of having to work with awkward tools, then it’s very likely you won’t get around to writing documentation until you absolutely have to.

With all this in mind, the idea of the “documentation retreat” was born. The idea is a workshop at which you have nothing to do for a few days other than write documentation. The first day would involve some Dexy tutorials so as to make it easy, fast and fun to write documentation, along with some discussions about what types of documentation should be included in a project and what tools to best use to write each of these. The rest of the workshop would involve writing documentation in an environment with technical support and an immediate opportunity for discussing any issues/questions that arise. While training and support in Dexy will be provided, participants will of course be welcome to use other tools either within or alongside Dexy if this proves to be more beneficial and provided these tools allow for the project goal of long-term maintainability to be met. By the end of the workshop, participants will have a great toolkit for writing documentation, as well as a significant quantity of maintainable, high-quality documentation already written. Once this initial hurdle has been met, it is hoped that it will then be significantly easier to maintain documentation over time, and with the adoption of a tool such as Dexy, to make writing documentation an integral part of the programming process, much like testing has become for many people.

Speaking with Mahendra, we began to plan just such a ‘documentation retreat’, which is provisionally scheduled for 21-23 June 2011. Please keep an eye on this blog for further announcements and registration information for this June event, from which we expect developers to leave with a significant part of their documentation done for a chosen project.

Initially, there will be a one-day workshop to be held on April 5 in Bath. This event will be a pilot for the main event and will also be used to train additional facilitators who will assist with training and troubleshooting at the main event.

At this point, we are inviting you to complete the form below if you would like to be considered for the pilot which will be held in Bath on 5 April 2011. The deadline for completing this form is Monday, 7 March 2011. This event will be free and we have a maximum of five places available. After completing the pilot course you should have a good start on documentation for your project and also have a new toolkit which will help you to complete your documentation and then maintain it over time. Part of the ‘deal’ will be that those attending the early-access pilot will then act as facilitators for the much bigger ‘documentation retreat’ to be held between 21-23 June 2011.  We recommend that if you are interested in attending the pilot you need to meet the following criteria:

• You work or have worked in or with UK Further or Higher Education as a developer
• You are completely comfortable working at the command line
• You have some documentation to do and you are *interested* in doing documentation
• You enjoy helping others and you are patient
• You are available to attend the workshop scheduled for 21-23 June 2011 (location TBD) and you are willing to act as a facilitator at this event.

Please complete the registration form here if you meet the criteria and would like to apply for a place. Don’t worry if you are not picked for the pilot, you will still be able to come to the ‘retreat’ in June. As mentioned, keep an eye on this blog for further updates and registration information. In the mean time of course, feel free to explore Dexy on your own!