Documentation for Typo

For the class project in CS527, I am documenting the Typo content management system. Typo is the back-end that powers this weblog.

We are supposed to follow the documentation style from the Documenting Software Architecture Views and Beyond book. There is some good advice there but following it blindly will make the documentation too cryptic for even the most enthusiastic readers.

I have tried to follow the different views that the book suggests. The end product will have module view, component-and-connector view and allocation view types. Whenever possible, I have also included the code excerpts from Typo as well as links to external sites that describe the rationale behind certain design decisions. Each view is explained in the text and related views and tied together.

I do not intend to produce something that mimics the example at the back of the book. The example at the back of the book is meant to cater to various stakeholders so there is an obscene number of views. Moreover, each view follows a template that needs to be described as well.

The stakeholders for Typo are mainly Rails developers and web designers. Therefore they are more familiar with some of the terms that we will be using. I have written it in such a way that it is possible to read the entire documentation from cover to cover without it being too boring. After all, what is the use of documentation that no one reads. This documentation also serve as a guide on where to obtain more information on Typo. There is no authoritative source of documentation for Typo at the moment, even though there are various tutorials on the web on how to modify certain extension points for it.

The advantage of an open source project is the availability of the source code. Thus, this documentation should serve as an overview of the relevant modules in the source code. Moreover, Typo is an evolving project so producing a detailed documentation that will only last for one version is not going to be useful. Instead, by documenting the major modules that are unlikely to change, that documentation remains useful even in the next release.

Incidentally, this is the first time I am using LaTeX for writing so there could be some weird artifacts with how the text looks. I describe my process of learning LaTeX on my personal weblog.

An auto-generated draft is available here. It will be updated frequently but I want to get a version out first since Prof. Johnson requested that we post a copy by the end of the week --- Saturday is the end of the week. The sections on Module views and Allocation Views are pretty complete but the rest are probably going to undergo more changes. Right now the figures have explanations in the text but they do not have a key associated with them. The book suggests that each figure be accompanied by a key. I am still deciding if this is really necessary.

Update: The link to the documentation now contains a complete version of the documentation. By complete, I mean that it has all the views that I had planned to address. I have also just read through it and corrected some minor mistakes. Unless I decide to include a new view or receive comments to change certain aspects of the documentation, the final version will be similar to the current one. The first draft is still available from here for comparison.