Frank Mittelbach:
I think it is extremely valuable to combine the development of software (actually anything) with the task of writing about it in some way. Trying to explain to others the functions and concepts behind a creation helps a lot in finding out whether or not something is going to work in practice. If you can’t explain it or if the explanation turns out to be horribly complicated, then there is something fundamentally wrong with your creation and you should return to the drawing board.
Very important here is that one does not stop at simply documenting functions or menu items (though that is a start) but effectively tries to document the usage flow and the reasons why one would do things in one way or the other. Often enough (with free software as well as commercial software) you find only rudimentary documentation that tells you that such and such feature exists but never explains why one would want to use the feature in the first place. That type of documentation, while necessary, will not help in improving your tool (and often enough it turns out that such features only got implemented because they were easy to add without providing any real benefit).
So yes, documenting ideas and work flows has always been an integral part for me of developing and/or improving software, both my own as well as software from others. In The LATEX Companion, for example, a good proportion of what I describe is software developed by others, and the process of trying to explain how to use this software and finding good usage examples led in many cases to improvements in syntax or features after some discussions with the authors.
Therefore my advice to developers is to always try their hands at documenting their own creations or at least find somebody who does it for them (starting from the initial development!) — and carefully evaluate the findings from this process: it will result in noticeable improvements in the product.
Gianluca Pignalberi and Dave Walden, "Interview of Frank Mittelbach". Joint interview published by the TeX Users Group and the Free Software Review (2006).
[end]
Comments are enabled.