Every once and a while I go through old notes, todo items and such. Today I bumped back into the GNU Proofreaders mailing list. It's an effort which herds cats towards improving documentation.
Take, for example, non-English programmers who want to get help with their documentation. They would have a resource to turn to for help.
I visited the GNU Proofreaders mailing list, thinking I may subscribe to it and I may devote some off-time with helping. But I was greeted with this message:
GNU documentation proofreaders list. Due to lack of response, this list has been discontinued, although archives are still available. The GNU maintainer information document will get updated in due course, unless someone actually notices this and wants to do proofreading :).
There is still an archive, and when I look through it .. well it seems that this project never really got off the ground in the first place. That's a real shame, because good documentation is almost as important as good software itself. Well, that is to say that a good program is obvious to use, and also has good hints within it .. but failing those things - which most software definitely does - a program should have good documentation, and most especially good usage examples. (man pages, HELLO are you listening?!)
There are still some lingering mentions of the GNU Proofreaders idea:
I think that the fact that the list and presumably the whole project has been shut down since 2007 and there are lingering mentions reveals a general attitude on documentation in general.
Documentation should come first. No really, it should. Even before programming, even before a scrap of code. Documentation is planning. It's more than that, it's the very soul behind the mission statement. It's the first introduction and the best helping hand anyone ever gets. Good documentation never sleeps and never stops working.
I've found that most Linux documentation exists as some kind of ghostly afterthought, or as a kind of insulting user-documentation. I do like the idea of user documentation, but isn't something fundamentally wrong when the users find it necessary to self-assemble to help other users? I love wikis, I really do, but the wiki should be dominated by the programming team.
Programmers are not always writers, and there are many kinds of person working with software these days. But to me a good programmer is always also a good commenter and a good documenter.
A lot of software is at the level of "cool hackish project", which solves a specific niche interest the programmer had. Usually what happens is that there is no need for documentation since the programmer already knows what they need to know to use their own software. Documentation comes as an afterthought at best, and sometimes only as a reaction to user-pressure.
Some programmers feel documentation is the icing on the cake. They do it last, and with great pride as a flourish - a finishing touch to a "completed" project. I've seen some really great documentation - really thorough and really personable - but it still doesn't seem right.
A fantastic program with poor documentation is no better than a mediocre program with fantastic documentation.
Let's take an actual example. wmctrl is an example of shockingly few programs which are used to control X Windows application windows from the commandline. I was first introduced to it when I went looking for a non-KDE way to automatically control window properties (size, position, etc).
2014-08-01 - I've since learned there are a few other such programs. As of this date I have not looked into any of them. My need for this functionality has been gone for some time now. I've kept plenty of notes though.
But the documentation! Oh the documentation could be so much better. I had to struggle and struggle to get it working, and it still took me forever. The program wasn't popular enough for there to be good user-documentation out there, nor for there to be random blog postings with tidbits to help me figure things out.
But I was passionate. I did things the only way I knew how. I figured everything out, I made test cases and examples and I wrote some of the best damned documentation for wmctrl which I possibly could.
But should I have been put through that hell? No.
Examples are all that I was looking for. If documentation was all about examples and with a small amount of explanation, I would be quite happy. I'm very examples and tutorial-driven. I do realise others may not be, but I recognize that I'm this way. I get impatient when there is too much working.
I'm so much this way that I really like test case-driven stuff. I think that a project should come in this form:
Begin with a mission statement which includes an explanation of the project's existence, features, planned features etc. Give a general notion of the project and relay the personality of the people.
The list of features in the mission statement almost become the functions/procedures or components within the project itself.
For each one of those components there should be one test case for every possible variety of use.
Each test case should be a user-useful example.
Each example should include a rough outline of the test case's goals and should discuss the usage and include a mention of any fringe usages. This is kindof like the "mission statement" of the test case / example itself!
The programming comes last. The programming proves its existence by passing the test case.
What's left after all of this is some truly functional documentation. For a more technical program, the documentation can stop right here, and it would be excellent to an indescribable degree. Of course, for documentation targeting "regular users" there will need to be some elaboration including screenshots, much more language and such.
I'm also of the opinion that all program documentation - and let me emphasize this.. no, let me scream this right out loud - ALL PROGRAM DOCUMENTATION, except for installation and running troubleshooting, SHOULD BE BUILT INTO THE PROGRAM ITSELF.
Every single function within the program should have companion documentation right there - right beside the feature. I really like'd Microsoft's use of the little "?" at the top-right of their windows, which let a person hover over lines and get an explanation. I really like when documentation is immediately visible and not hidden in a separate format like a man page or even an external help file.
I don't care how organized that help file is - it's nowhere near as convenient or powerful as a bit of text right next to the feature. Hover over a menu item to get a description in the status bar. Hover over a button to get popup text. This kind of stuff is wonderful.
And how, may I ask, is the best way to have documentation right up alongside a feature? Comments! Yes, in-line comments right in the code and which are brought right alongside the functionality to build the program. This is the real gold.
This is something I particularly like about concepts like Ruby's RDoc, which generates documentation from comments. Annoyingly, the RDoc documentation itself isn't particularly usable for us regular humans.
The real gold would be comments alongside the test cases alongside the code which is brought into the code to be inline documentation right there with the feature itself. This can't be a unique thought, can it?
I mean.. I laughed when I saw my old todo/wishlist notes. It went something like this:
FTP is annoying. Why can't I just have the text file downloaded for me, and automatically re-uploaded? I should be able to edit a page through a form. There should be some non-HTML human-usable markup language so I can do common things faster.
Yeah, I wanted a wiki before they even existed. I'm pleased someone out there knew what I wanted and made it for me. =)
I feel the same way about this kind of documentation. It should drive the whole project and the whole program. No feature can be finished without a test case. No test case can be finished without documentation. Period.
