Gnome 3 and Documentation

[Shaun McCance <shaunm gnome org>]

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