Last year I had the megalomaniac idea of rewriting the user documentation of GNOME Evolution from scratch.
As GNOME 3.2 approaches quickly I had to realize that perfect is the enemy of good. After putting the remaining TODOs into the random categories FIXLATER, NEEDHELP, MUSTFIX and DONTCARE and after having no MUSTFIXes left, I merged the new User Documentation today into the codebase. It will be available on library.gnome.org from August 17th on (that is when the next tarball 3.1.5 will be released), and while a few pages could still be improved I can at least promise that nothing is worse than in the old manual.
I’ve mostly failed to attract contributors but I welcome everybody to fix any remaining issues by searching for TODOs in the checkout (how-to), to translate the new docs to your favorite language, to file bug reports about stuff that is improvable, and to buy me some icecream or beer at Desktop Summit Berlin tomorrow. Or next year in Brno in case our proposal will be successful. Cheers!
Thanks for contributing these docs. I’ve always wanted to ask a documentation author this question. Sorry if it’s a bit rude or sounds like I don’t appreciate your work, but I’m really curious as to this problem.
Why do the docs for all applications list the same absolute basics every time?
Your docs explain how to start Evolution, by explaining to go to the applications menu, click Evoution… Do you really think someone who did not understand how to start an application in the first place would be able to get as far as reading your docs, or would know how to start the docs reader, or would even know that docs exist? Do you think any Gnome user out there would go “Damn… I just can’t figure out how to start Evolution. I know, I’ll check the docs…”
Later on when talking about lists of messages you say “Navigate the message list by using the arrow keys on the keyboard.” Again, do you think there is a single soul out there who looks at the bog standard list view control, which is pretty much the same on every computer interface ever, and thinks, “Damn… I don’t know how to move between these messages. Normally I would use the arrow keys, but I don’t know here, instead of trying, I’ll look it up in the docs…”
I’m really sorry if that sounds unappreciative, and I love the fact that people are spending their time writing docs for us, but do you honestly think anyone will ever use those two snippets, or the millions of others like it in every set of docs ever?
Haven’t you effectively written what could be considered ‘dead code’ there? Nobody will ever need it.
Can’t we write a global, how to use a computer doc, then a global how to use gnome doc, then an evolution doc that assumes that prior knowledge?
Thanks though!
Hi Bob, no no, your comments are welcome!
I assume that you refer to the old manual? I can’t remember that I describe how to start the application in “my” new manual, as I agree with you (and the mindset). And you will also find instructions like “To save, click Save.” in the old manual. Similar category.
About navigating in the message list I’m less sure. It might be not needed but shouldn’t hurt, especially as it’s on the page “Using shortcut keys to read mail” which also covers many other ways to use the keyboard for doing things. If your workflows have been very mouse-intensive it might be useful.
I’m quite sure that the new Evolution docs don’t cover generic GNOME-wide stuff that should be in the GNOME Desktop user guide instead, but if you find such sentences in the new docs feel please free to add more comments!
“perfect is the enemy of good” – I’m taking that.