By Kieren Diment (kd) aus Sydney.pm
Datum: Mittwoch Juni 9, 2010 10:50
Dauer: 100 Minuten
Language:
Tags: catalyst documentation moose perl
Documentation is an extremely important part of open source software development but it is frequently neglected. In part this is because of the "scratching an itch" nature of many open source projects. In fact some of my own open source projects are woefully under-documented due to time constraints and the use case of the code I'm writing at the time.
When I first became involved in the Catalyst project, Catalyst::Manual::Tutorial contained some explanation of the architecture of a Catalyst application, with some example code, but if the user followed the tutorial through it did not result in working code. This obviously impaired my ability to use the framework, and left me with the only alternative which was to finish writing the tutorial myself. As well as buying me a good deal of free technical support by contributing back to the community, this eventually lead to a strong culture of example driven documentation in the Catalyst code base as shown through the now comprehensive tutorial, and the many examples written by members of the community in the Catalyst Advent Calendar. So the first part of this talk will look at the community benefits of producing documentation.
The second part of this talk will introduce the anatomy of different kinds of documentation, including technical docs, user docs and code comments, with the importance of each outlined. From here I will move onto the important links between the test suite and documentation. I'll talk about the innovative approach that Matt Trout took in the Catalyst book by linking version control commits, the test suite and explanatory text in his "Extending Catalyst" chapter, including the up-side and down side of this approach. Finally I'll go on to explain the link between testing and documentation, going into the rationale behind the chapter of the Catalyst book on the Chained dispatch type.
Documentation is easiest for code with a narrow scope, and few 'moving parts'. In the final part of this talk we'll audit the Moose documentation (and its extensions) for clear examples, and describe the anatomy of writing example driven explanatory documentation which will leave the programmer clear on how to use the library, and about the future direction that their code should take. The key take-home message of this part of the talk is that for documenting code libraries with complexity we need to account for the high intrinsic cognitive load inherent in explaining programming issues, and ensure that not too much is demanded from the reader.
We'll finish the workshop by auditing the documentation for Moose and its extensions, looking for places where complete working example code will be useful. Then in the workshop part of the talk we'll write examples for Moose and its extensions which can be easily folded back into the documentation.