Software documentation is one of the missing pieces of the software game. So many systems are not well documented. It’s also not really part of the budget of most systems. The client certainly doesn’t want to spend time on something so abstract. They don’t really understand why a system needs to be documented.
i do agree that this is an aspect of software development which is lacking, however i think the solution is not in more and better documentation; i think the solution is in better systems.
Recently, i spent a little time thinking about how to enable development of an open source system i am working on (cln). There were a few things i decided to do to help get more people involved in the development. The first and foremost is to make the system interesting. As to whether we have achieved that – it’s hard to say right now. The second step we took was to make sure the system was easy to get going. We’ve done that in a few ways. The first is to notifiy the user of important configurations they need to make, through acccessing the system. This is the idea i want to point out. Essentially, it is documentation embedded in the system. Now, the reason we did that was to ultimately enable the documentation to grow or even change. This means someone could take our software and customize it to instruct the user in a different way. We also took this path, knowing that documentation is often left to the end. By making it part of our system, we enable others to improve the documentation as they experience it.
So rather than creating ‘notes’, systems should reverse the process and offer help when needed. This model has been implemented before by software like dreamweaver to some success. i think we just need to continue it.
