Re: Gnome 3 and Documentation

[Paul Cutler <pcutler foresightlinux org>]

Hi Shaun,

Thank you for taking the time to write this email.  I agree with you
on all the points below, and for the last day or two have been trying
to figure out how best to formulate my questions.  I think there are
more questions than answers at this point, but let's talk next steps
in addressing the points you make below.

As we think about moving towards GNOME 3.0 and the documentation
opportunities we have in front of us, this section of your email in
particular stood out to me:

> 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.  Bottlenecks are bad, mkay?

I'd like to thank Milo for responding, but it kind of scares me how
quiet the list has been on this topic.  I know personally I've lurked
on this mailing list for a few years, rarely posting. I bet there are
some more people out there like me who want to help but who might not
know where to start, and I think this is a great opportunity to grow
the docs team.

So let's do this.  Let's get a team together.  As I'm fairly new to
helping out the Docs team, is there a method that has worked in the
past?  Shall we schedule a meeting in IRC and see who can make it?  At
a minimum, it could give us an opportunity to discuss current statel,
let us see who can make it and wants to lend a hand helping (and those
interested in helping but can't make it), and capture some action
items of what we can attack next to lay the groundwork for what needs
to be done over the course of the next year.

If not a meeting in IRC, we could take your email below and break it
up into separate discussion topics and get the ball moving.

I'd love some feedback from other people on the list - let's not waste
this opportunity!

Paul

On Mon, Apr 6, 2009 at 2:29 PM, Shaun McCance <shaunm gnome org> wrote:
> 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
> documentation.  Obviously, an XML format is no substitute
> for good planning and writing.  But the format can have
> a big impact on how we write and organize information.
>
> Task-oriented documentation is considerably more helpful
> to users, because it attempts to teach them in terms of
> things they care about.  It helps beginners get a grasp
> on things without inundating them with concepts.  It can
> also create a better path for learning and exploration,
> encouraging beginners to become intermediate users.
>
> Mallard is designed to be easier for writers.  It avoids
> flooding them with too much markup while still retaining
> enough richness to format our documents consistently.  It
> reduces the mental overhead for organizing concepts.  Its
> design is influenced by my experiences and difficulties
> with numerous other systems.  It is most certainly not
> perfect, and I'm sure we'll revise it with more time and
> experience.  But I do believe it's substantially better
> than anything we're doing now.
>
> Furthermore, Mallard is designed to be friendly for our
> vendors.  The reality of Gnome is that it's distributed
> by numerous vendors with their own plans and visions.
> The desktop as experienced by our users is not pure Gnome.
> At best, it's a superset of what we produce.  More often
> than not, there are significant changes.
>
> Mallard is designed to allow our distributors to build off
> of our documentation with little or no patching.  They can
> easily add content and have it seamlessly integrated.  It
> isn't buried in some "vendor patch" section.  Mallard's
> organizational model means we can present users with the
> right information in the right places, regardless of who
> wrote it.
>
>
> It's a Big Job
> ============================================================
> We have about a year to do more than we've failed to do over
> the last decade.  If we were a commercial organization with
> paid employees, I'd recommend hiring a team of no fewer than
> eight full-time technical writers.
>
> Obviously, that's not going to happen.  We need to rely on
> our intrepid volunteers.  Assuming we can recruit enough,
> there are problems we face that can't be solved by adding
> more heads.
>
> First, even experienced writers aren't necessarily skilled
> technical writers.  I've discussed in general what kind of
> documentation we need, but producing it takes experience
> and skills.
>
> We also haven't solved many problems that hinder our work.
> One of the biggest problems is the difficulty of getting
> working prototypes in front of writers.  It's very hard
> to write about something you can't use.
>
>
> But Somebody's Got to Do It
> ============================================================
> This is the part where I'm supposed to present the solutions
> to all the problems I just mentioned and end on a positive
> note.  Unfortunately, I don't have all the solutions.
>
> 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.
>
> As for how to write, I will do everything I can to train
> writers.  I've been collecting notes which I hope to turn
> into a book.  The book isn't going to happen in the next
> year, but the notes can help me help people.
>
> 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.  Bottlenecks are bad, mkay?
>
>
> Insert Motivational Message Here
> ============================================================
> The scope of this is daunting, I know.  But it's also an
> incredible opportunity for us.  Gnome has one of the most
> vibrant and amazing communities I've ever seen.  I truly
> believe we can pull this off.
>
> --
> Shaun
>
>
> _______________________________________________
> gnome-doc-list mailing list
> gnome-doc-list gnome org
> http://mail.gnome.org/mailman/listinfo/gnome-doc-list
>