Overhaul TortoiseHg Documentation with a New Approach
Created originally on Bitbucket by tomschr (Thomas Schraitle)
First of all: Thank you for all your efforts with TortoiseHg! I like it very much and it is really a very helpful piece of software.
Although the GUI is easy to understand, sometimes I need inspiration or a hint how to do a specific task. The sad part is, the TortoiseHg documentation confuses me and does not always help me with my questions.
Let me explain why I think the current state of the documentation should be improved. Sorry if it is a longer text. I wanted to show the reasons to give a better understanding of the background. So please stay with me. :)
What do Users Want and Need?
Coming from a documentation background, I've experienced a shift in how documentation is perceived and used. These are the key points that I've collected from polls, articles, meetings, summits etc.:
- Users (normally) don't read documentation, at least not sequentially from cover to cover.
- When users (have to) read documentation, they usually have a problem.
- Users expect quick answers to their problems. Fast.
- Users are not (always) interested in background information.
- Users want to read short documentation. Nobody wants to digest long texts.
Of course, the above points are very condensed. It depends on the documentation, the user base, the software etc. However, it's a general trend that I see in the IT industry in regards to documentation.
Think of yourself: what was the last documentation that you've read? Did you read it completely? What did you like about it, what did you hate?
What's are the Consequences?
The above experiences lead to several consequences how documentation should be written:
- Know your target group.
- Keep documentation concise.
- Write topics which covers a task or solves a problem.
- Give step-by-step instructions (procedures) to help your users.
- Avoid referential material just for the sake of having "some" documentation.
What are the Issues With the TortoiseHg Documentation?
You may think what has this to do with the current TortoiseHg doc?
For example, let's think of a user scenario: Joe needs a Mercurial GUI. His friend Bob recommends TortoiseHg to him. Now Joe visits the homepage and downloads the archive. What do you think Joe want's to know next? Some of his questions could be:
- How do I install the software?
- What are the first steps? Which are essential and which are optional?
- Can I use TortoiseHg with my existing repositories?
- How do I clone a remote repository?
- Do I need to understand Mercurial?
Does the TortoiseHg documentation answers his questions?
Lets assume, Joe finds out some of his answers to these questions "somehow". As he uses TortoiseHg more and more often, his questions have been changed:
- How do I branch?
- How do I commit only some changes to a file?
- How can I compare two versions?
- How do I use patch queues?
I've gone through the documentation on ReadTheDocs. Sure, some of the above questions are addressed somewhere somehow, but I think the overall structure and content can be improved.
For example, the What's new? section is probably important when you know TortoiseHg already. But for a beginner?
Installation is not covered at all in this guide. Maybe it isn't that important, but there might be several recommendation were to install it.
From my perspective, the current documentation has the following issues:
- Target groups are not always clear (is it for a beginner, a casual user, a developer?)
- No consistent step-by-step instructions.
- Answers are sometimes hard to find (no, the search button is not the solution)
- Different styles: There is tutorial style and FAQ style.
- Different title styles: explanation (substantive style) with tasks (verb style).
How to Solve the Issues?
Ok, here are my general suggestions:
Split the complete documentation into several sub-guides (know your target group!)
For example: "First Steps Guide", "TortoiseHg for Daily Use", "TortoiseHg for Advanced Users", " "TortoiseHg Contributors Guide", "FAQ", etc. Whatever you think it's useful for your readers.
The reason for this is different users have different needs and questions. A TortoiseHg beginner will probably start with the "First Steps Guide". It's very likely he will find its questions there. A more experienced user will look into the "TortoiseHg for Daily Use". You get the idea. :)
Structure your guide(s) accordingly.
A "First Steps Guide" needs probably other structures than a "TortoiseHg Contributors Guide" or a "FAQ". Mixing the two just confuses your readers.
Use step-by-step instructions
Procedures are very helpful: readers see how many steps it takes to perform a specific task. Why? Because a reader thinks "Oh, I need only 6 steps to do this" in comparison to "Hmn, do I have to read this hole section which are several pages long? How do I start? Boring, I'm lost, lets skip that..." Bang, you've lost your reader!
Use verbs instead of substantives (even in titles)
Verbs mean life, substantives death. For example, "Click File > Open Repository and select a folder to work with your local repository." is a clear instruction. Also the title "Creating New Repositories". However, "Workbench", "Settings" etc. does not sound as a task.
By the way, I like the BitBucket documentation from Atlassian. Lots of my above points are adressed there.
To be a bit more concrete, I would like to give you some ideas on how to improve the section TortoiseHg in daily use:
It starts with a "5.1 Common Feature". This sounds like reference material. No real action is shown to the user.
The "5.2 Windows Explorer Integration" and "5.3. GNOME desktop integration" are preparation tasks. Unfortunately, the title doesn't reflect that. What about a more active, user oriented title? Something like "Integrating TortoiseHg for Desktop Usage"
The section "5.4 Workbench" is reference material again. No user wants to read or see the menus. Sorry, but IMHO this is useless and doesn't bring any value to your users.
Ahh, section "5.5. Create a new repository" starts with a verb. Great! This is much more useful than the previous section(s). If you write the instructions as step-by-steps this will be perfect. :)
Same applies to the rest of the sections. Ok, I think you get the idea, so I'll omit my wordy explanations. ;)
Why Should we do this?
Of course to help your existing users, attract new users, and to find answers to problems faster.
You could go even further: link from the GUI to the documentation. A user wants to know how to commit something? Great, click on the "?" button and read how to do it in 4 easy steps. With such a concept, the user is only a click away from his answers. :)
Don't underestimate good documentation.
Thanks for reading. :-)