Re: Gnome 3 and Documentation
Hi Shaun, On Mon, Apr 6, 2009 at 8:29 PM, Shaun McCance wrote: > What Documentation We Need > > It's very important that we have a replacement for the aging > user guide. A new user guide is our opportunity to showcase > what users can get done with our desktop. Without a new user > guide, we risk alienating lots of potential users. I would tend to go a bit further, and say that we should stop talking about a user guide for Gnome at all. The concept of an all-consuming guide doesn't fit very well with the "task based help" approach which you've (rightly) propounded elsewhere in your email. By way of comparison, we used to have a single all-consuming "desktop guide" in Ubuntu help. We gradually realised, with the help of Matthew Paul Thomas, that a "guide" this was the wrong way to look at desktop help. This led to a breakup of our documentation into separate categories, and a change of emphasis from a complete guide to different help pages. The move is documented here: https://wiki.ubuntu.com/TopicBasedHelp This may be a linguistic distinction, but I think it's quite important for how we look at documentation and the task that Gnome faces as an upstream provider. It's key that the documentation that is produced upstream offers extreme pluggability so that distros can easily drop material into the structure provided by upstream to cater for the situations where they customise and add to the Gnome desktop experience. I know that you've very aware of this need because it is central to the Mallard design, but I wanted to get this thought out there. > Task-Oriented Documentation > > "To open a file, choose File ▸ Open." > > Our current documentation reads like stereo instructions. > When they have any real information at all, it's either > purely descriptive of the interface or a regurgitation of > the internal design of the software. The documentation > isn't designed to teach anything. We have no plans, so > we just pour everything we know into DocBook. Too much > information gets in the way of learning. This is true, of course. And I agree that teaching is an essential part of what the documentation should do. However, it's a reality that a lot of computer users really do need walking through the buttons they need to press when performing a particular task, and that when they learn how to do it the first time, they quickly forget. So I'm sympathetic to documenters who make an effort to specify the exact buttons that need to be clicked, and I think that a middle ground needs to be struck. > If we could get a a build team together to produce virtual > machine images of vanilla upstream Gnome, it would be very > helpful. We need these sooner rather than later. Writers > need to get involved earlier in the development process, > and we need our developers to be responsive to writers. Just to reiterate the importance of this - this is the sole reason why I haven't contributed more to Gnome documentation. I'm worried that a patch I produce will be inaccurate because Ubuntu customises Gnome in particular ways, and a way to run a vanilla Gnome build (even in VirtualBox or another VM) is absolutely essential. > I think the best way to get started is for me to have a > small crack team that lays the groundwork with me. We > would work closely together, sharing our knowledge and > experience. These people could then help me in training > new contributors and communicating with our development > teams. I'm in and will do what I can. As others have said, a roadmap is essential. For example, if Mallard will be implemented within 3 months, then the approach will be very different to the approach needed if Mallard won't be implemented for another 9 months, or at all. -- Matthew East http://www.mdke.org gnupg pub 1024D/0E6B06FF ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Gnome 3 and Documentation
On Wed, 2009-04-08 at 17:53 +0100, Matthew East wrote: > Hi Shaun, > > On Mon, Apr 6, 2009 at 8:29 PM, Shaun McCance wrote: > > What Documentation We Need > > > > It's very important that we have a replacement for the aging > > user guide. A new user guide is our opportunity to showcase > > what users can get done with our desktop. Without a new user > > guide, we risk alienating lots of potential users. > > I would tend to go a bit further, and say that we should stop talking > about a user guide for Gnome at all. The concept of an all-consuming > guide doesn't fit very well with the "task based help" approach which > you've (rightly) propounded elsewhere in your email. > > By way of comparison, we used to have a single all-consuming "desktop > guide" in Ubuntu help. We gradually realised, with the help of Matthew > Paul Thomas, that a "guide" this was the wrong way to look at desktop > help. This led to a breakup of our documentation into separate > categories, and a change of emphasis from a complete guide to > different help pages. > > The move is documented here: https://wiki.ubuntu.com/TopicBasedHelp > > This may be a linguistic distinction, but I think it's quite important > for how we look at documentation and the task that Gnome faces as an > upstream provider. It's key that the documentation that is produced > upstream offers extreme pluggability so that distros can easily drop > material into the structure provided by upstream to cater for the > situations where they customise and add to the Gnome desktop > experience. Actually, I disagree. I think you're averse to the term because we've been using it wrong for a long time. When I think of a guide, I think of somebody I hire to show me around a city. She doesn't just rattle off everything she knows and send me out on my own. She gives me useful suggestions and answers my questions as they come up. The more we can make our documentation like that guide, the better off we'll be. I would argue that, document titles notwithstanding, we've never actually produce any guides. We've only ever made manuals. > I know that you've very aware of this need because it is central to > the Mallard design, but I wanted to get this thought out there. > > > Task-Oriented Documentation > > > > "To open a file, choose File ▸ Open." > > > > Our current documentation reads like stereo instructions. > > When they have any real information at all, it's either > > purely descriptive of the interface or a regurgitation of > > the internal design of the software. The documentation > > isn't designed to teach anything. We have no plans, so > > we just pour everything we know into DocBook. Too much > > information gets in the way of learning. > > This is true, of course. And I agree that teaching is an essential > part of what the documentation should do. However, it's a reality that > a lot of computer users really do need walking through the buttons > they need to press when performing a particular task, and that when > they learn how to do it the first time, they quickly forget. So I'm > sympathetic to documenters who make an effort to specify the exact > buttons that need to be clicked, and I think that a middle ground > needs to be struck. Absolutely true. One could write an entire chapter of a book on knowing your audience. In an ideal world, we could have topics tailored exactly to every user's skill level and learning style. But nothing short of that hypothetical human guide is going to accomplish that. Getting the level of information right is an incredible balancing act. If you fill it with too much hand-holding, more experienced users will be frustrated and unable to use the documentation well. If you fill it with too much conceptual information, beginners' eyes will glaze over. If you look at the commercial publications sector, you'll see a wide variety of books on the same subject. These address different skill levels as well as different learning styles. We can only do so much on our own. Sometimes it comes down to a numbers game. When you can't do everything, you do what will be the greatest benefit to the greatest number of users. -- Shaun ___ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list
Gnome 3 and Documentation
Gnome 3 presents us with a wonderful opportunity to get documentation right. I believe documentation will be very important to the success of a new user experience. Furthermore, I believe that we have a rare chance to bring out new documentation with a bang. If we do it right, people will take notice and begin to trust in the documentation again. This email outlines my view on what we need to accomplish and how we can accomplish it. This is based on my years of experience not only with Gnome documentation, but in the commercial publications sector as well. This is a long email. Here's a table of contents: * The Importance of Documentation * What Documentation We Need * Task-Oriented Documentation * It's a Big Job * But Somebody's Got to Do It * Insert Motivational Message Here The Importance of Documentation "Nobody reads the documentation anyway." People do, in fact, read good documentation. Well-written, task-oriented documentation can actually be an enjoyable learning experience. What people won't read are interface descriptions. Documentation is sometimes the first exposure users will have to our software. After seeing some marketing blurbs and release notes, many users will browse the documentation to see what the software is really capable of. These users are unlikely to read the documentation in depth, but if the documentation is done right, it can serve as an excellent marketing tool. "Good user interfaces shouldn't need documentation." New user interfaces, no matter how well-designed, are scary. Good documentation can help acclimate users to the interface, showing them how they can make effective use of the software to do things they actually care about. Documentation serves as a safety net, making users feel more comfortable and more willing to explore. This only works if users feel they can trust the documentation. Documentation also helps create more experienced users. More experienced users are more likely to continue being users. Casual users are easy to lose. By creating more experienced users, we open the door for more enthusiasts. This, in turn, can help us get more contributors. Experienced writers involved early in the development cycle can help create more user-centric interfaces. By focusing on how to present the interface to users in ways they care about, writers can help discover ways the software itself could be improved. They're like surrogate designers. Remember that the users who complain to us are a very small minority of dissatisfied users. They're the ones we have a chance of keeping. Most users will just silently stop being users when they're stumped. Though most users won't read the documentation before using the software, many will do so before giving up. Our job is not to fail them. What Documentation We Need It's very important that we have a replacement for the aging user guide. A new user guide is our opportunity to showcase what users can get done with our desktop. Without a new user guide, we risk alienating lots of potential users. Application-specific help is, of course, also important. But the reality is that we will have to prioritize some things lower to get anything done at all. Applications that have simple or very traditional interfaces are less important. It is critical that we have developer documentation for any wicked new developer technology we want to promote. We're not just talking about API references here, although those are absolutely important. If we're going to push GJS/Seed as the next big thing, then we need expository documentation that shows first-hand how to use it to get stuff done. The same applies for any other new technologies, including any cool new GTK+ hotness. If we're to change the way documentation is done, then we need to produce a new writing manual and a new style guide. These can safely slip by at most one stable release. If we're exploring new user interface ideas, then we need an updated HIG. I'd say this can slip by a release if we have a draft or development version available by Gnome 3.0. Task-Oriented Documentation "To open a file, choose File ▸ Open." Our current documentation reads like stereo instructions. When they have any real information at all, it's either purely descriptive of the interface or a regurgitation of the internal design of the software. The documentation isn't designed to teach anything. We have no plans, so we just pour everything we know into DocBook. Too much information gets in the way of learning. Good documentation starts with good planning. Most people have heard me talk about Mallard, the project I've had in the works for some time now. Mallard is a documentation format designed to support task-oriented docum
