Archive for the ‘documentation’ tag
Automated Diagrams and Documentation
As I previously wrote, one of the ways to get through the task of documenting a project is to turn the documentation process into a coding project. Documentation sometimes seems pointless as the likelihood of anyone other than yourself reading it are low to nil.
To increase the chances pretty pictures always help. If they are also useful then the documentation starts to have real value. Up until now I’ve been using Microsoft’s Visio, but recently I tried out a couple of online tools.
Class Diagrams
The MapServer Mapscript documentation currently uses of diagrams made from ASCII text to illustrate relationships between classes. I’m not sure if these were generated automatically, but the images now appear a little dated. They do however have the advantage over an image of being able to copy and paste class names.
+-------+ 0..* 1 +-------+ | Class | <--------> | Layer | +-------+ +-------+
I tried to recreate these diagrams using the online service http://yuml.me/. On the site you enter your model description using a fairly basic syntax. From then on the same diagram can be accessed using different URLs, which are used to control display and formatting options.
The diagram above was created using the syntax below. You can play around with this sample by clicking here.
[Hashtable]1..1->1[Class{bg:yellow}],
[Label ]0..1->1[Class],
[Style]0..*->1[Class],
[Class]0..*->1[Layer{bg:green}]
Task #13: User Documentation
All projects I’ve worked on have a few days set aside for the dreaded “documentation.” Clients often try and reduce the billable hours set aside for documentation and when project delivery times are closing its often the last thing on a developers mind, so it gets cut from both sides.
I’ve come to the conclusion that a detailed and long word document, while it may tick the box on the client’s checklist, is an exercise in futility. No-one ever reads it, you’re lucky if you can even find it a year later, and its out of date the moment its written (or if its a rehash of the technical specification its never actually in-date).
My key requirements for user documentation are:
- make it easily accessible from within and from without the system
- have only one repository for the user documentation
- allow people other than the developer to create and edit the documentation
- auto-generate when and if possible