Hi Shaun, On Mon, Apr 6, 2009 at 8:29 PM, Shaun McCance <[email protected]> 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 [email protected] http://mail.gnome.org/mailman/listinfo/desktop-devel-list
