In the course of my digital media home efforts I have come across large amounts of documentation. This is good. Now, the problem is that in many cases this is stored in the form of a wiki, see for instance the recently mentioned ivtv driver project. Why is that? Yes, well, I'd like to join the choir complaining about the accuracy and actuality of the contents of a wiki. I myself have contributed to a wiki or two so I'm not against the idea as such, but since it is an effort that is largely uncoordinated it becomes inefficient when used to document an often fast-moving development project. Much of the information becomes stale and incorrect quite quickly and that creates a barrier to new users, especially inexperienced ones. I can sometimes guess what is valid info at a certain time and what is not, and I'm not afraid to ignore documentation when it doesn't fit my scenario and make my own adaptations, but it takes some experience to do that.
So, by all means use a wiki to flesh out documentation for stable projects, or to document certain (stable) releases, but in the case of something that's changing all the time, you have got to develop documentation along with the application, however brief or sketchy it might be.
Now, some would say that if you discover issues you could update the wiki - sure, but that's not what I can spend my days on! In order to do that I would have to research the issue and create a correct article, which could easily take days when you're not familiar with the subject area. I've got a day job... The developer(s) are of course intimately familiar with their app and so would be ideal candidates for documenting the stuff. I realize they too often have day jobs, but hey, docs are a part of the app!
No comments:
Post a Comment