Someone I work with asked for examples of good software documentation. I’m thinking of sending them the BBEdit and DEVONthink manuals. Maybe also linking to one of the Affinity apps’ online help. Any suggestions for other examples of really good end-use focused documentation I could send them?
4 Likes
I’ve always thought Carbon Copy Cloner does a good job with documentation. Here’s the latest pdf: https://bombich.scdn1.secure.raxcdn.com/sites/default/files/bulk_pdf/ccc6-documentation-en.pdf
1 Like
The audience for said documentaation will affect the content. An audience of end-users will want different information from an audience of programmers from an audience of system managers.
Also the form of the documentation will contribute to the goodness. Online versus paper have different organisations; online in fragments based on screen size, paper in long/multiple pages.
Find yourself a copy of Designing and Writing Online Documentation by William Horton. It’s “old” but the principles remain the same.
2 Likes
This is a 180-page manual for a game, Old World, but a game is software. I think this one successfully balances organized reference, new user onboarding and advice. https://drive.google.com/file/d/1hb4dmDKxpf3pJJtpdFA4y4OOY-d2yrz1/view
The trend I’ve been seeing is away from formal printed/PDF’ed documentation, and more focus on UI/UX design in the product directly. All available controls are, ideally, visible in the interface, and you can get an overlay that spells out in more detail what each control does. Affinity and others does this on iPad, and you also have the “press-and-hold-Cmd” that gives you the keyboard shortcut overlay.
For anything more, you would expect a collection of simple screen recorded demos for the most common use cases at the developer’s site. Next step up are full, multi-hour tutorials for more complex products.
As for good exampes of documentation done well, I must say I find the AWS docs are pretty solid. Not for end users though…
2 Likes
I am not sure, if there are really large differences between end-user and third-party-programmers, when it comes to identify a good documentation.
From my site, a good documentation is one, where I could find an easy to understand explanation on every single function of a software (or any other “thing”), and how these functions are working together.
As a documentation of a “regular” software (no Public Domain and so on!) would not contain anything an other developer would be able to use for his own projects (if it is not a software for developing software!) any other developer would have the same interest in reading an easy to understand description of all functions, like any other “end-user” would also do.
Of course there are a lot of people out there, who do not have to read a Manual (or at least think so) because they had used (or even developed him/herself) similar software before, and are thinking that they already know everything anyway, but this is not the regular user case if it comes to a good documentation.
I would also agree with @airwhale that a good documentation today is not necessary a formal PDF or Printout. I think a good documentation is rather a bouquet of different sources for information.
I think Devonthink might be a good example for that, as they have a very good build in documentation, giving Hints and Tips on their functions, operating a good Forum where they reply to questions and are helping with problems, and where the user is also able to find help for a lot of reasons also with the search function, and who also are offering other means of information like their additional Handbooks, the TakeControl Editions, their Blog, their Q&A, their story of other users and so on.
An other good example for a good documentation (from my point of view) is the OmniGroup.
They have a similar bouquet of different sources of informations like Devonthink, with additional Podcasts, Videos or their “Inside”-Program and so on.
With this, they are both offering their information in different ways, and everybody is able to get the informations he needed to use the software in his/her favorite way. Some are reading PDF´s, some are using the Helpfunctions and some are getting new inspirations, on what to achieve with the software (or the solution for a current problem) by listening to relevant Podcasts, looking some Videos, or doing some lessons from the Inside-Program or similar.
I think it is the Mix, that differs a good documentation, from a “bad” one.
So I can give my partner who is not a programmer and after years of being a WIndows users has finally bought themslves a MacBook all the API documentation from developer.apple.com they will be able to find their way around macOS.
BBEdit is good. I’d also look at the Take Control of DEVONthink ebook.
Apple’s Style Guide is very helpful in terms of writing prose for the user (not the writer).
It’s really important to have a clear idea of who the user is. What do they need to know as basic assumptions?
Mark Anderson’s A Tinderbox Reference File is by far the best I know! Without this user’s incredible documentation Tinderbox wouldn’t be what it is.
2 Likes
Yes, of course you can, if you also shorten my statement to get that point… 
@Pete : NO, Tinderbox is the worst in the area of documentation. The Reference file is very difficult to follow for regular users; terrible example of documenting an app. That kind of documentation is ideal for developers; not for end users.
Bookends and Scrivener have the best documentations: clearly stated features with actual examples. I would personally nominate the documentation of Bookends as the best all around. Every feature is fully documented; and use examples are clearly stated. If you went through the documentation of Bookends, you are guaranteed to be a true master of the app. DEVONthink also has good documentation. But, there are a couple of features missing; that you need to scavenge through the user forum to fully understand their full functions.
6 Likes
I really like the Bike software manual here, written in Gitbook.
Incredibly easy to read and navigate.
Nick
PS - replied to a comment rather than the whole thread
1 Like
I recommend studying the Economist style guide, quite the most lucid description of how to write well that I have seen. I only wish I could do so as well as its journalists.
1 Like
I disagree Scrivener’s user manual is awful. Voluminous yes but I think their tech writer thaught they were writing a novel.
1 Like
Dellu, after I’ve heard of Tinderbox for the first time I searched for other users’ experiences and your blog post was one that I still remember - you were literally raving about Tinderbox. What happened?
@Pete:
I honestly don’t remember raving about Tinderbox. Re-reading my own blog, these are the entries I wrote about Tinderbox.
But, to be honest, Tinderbox is an amazing machine. Nobody can deny that. It can do what all others can’t do. But, you also have to know the downsides of it. It can be a huge time sink. You need to invest a huge amount of time (to learn the ins and outs of it) to use its amazing powers–and the resources are scattered and disorganized. It is very unfriendly environment for beginners.
It is not that I disliked it. I just want to tell people the environment they are getting into.
1 Like
Yes, it is extended, and can be boring to read. But, I personally like it because it is exhaustive. I don’t need to read it from top to toe: can jump using the outline.
1 Like
I always find what I need, and understand the clear explanations, from Curio’s documentation.
Katie
3 Likes
I find that impossible. At any point in the “narrative” the tech author presumes that the user has read eveything up until to there for it to make any sense.
1 Like
One of the reasons I like Take Control books is that they make it very easy to find what you need in that moment to accomplish a specific task.
1 Like