Re-energizing Our Documentation and Support Experience

[Phil Bull]

Hi Jono,

Sorry for the long delay in picking this up! Thanks for encouraging us
to discuss this issue. See below for a few comments.

On Wed, 2011-06-22 at 06:37 -0700, Jono Bacon wrote:
[...]
> Shortly before UDS, Jim Campbell wrote an excellent blog post about the
> docs team, and I had seen his good work before. I sponsored him to UDS
> to come and talk more about docs, and at UDS I had lunch with him to
> start growing a relationship. I committed to Jim that I want to help see
> the docs team thrive in the 11.10 cycle, and Jim and I are having some
> regular calls where we can sync up on what is going on with the team.

I'd like to apologise for not attending UDS - I just couldn't afford the
time out for this as well as the GNOME stuff I've been doing. I think
it's important for teams to meet in person every so often because it
really is a wonderful way of getting a lot of planning and coordination
done in a short space of time. We should take this more seriously as a
team.

> We had a call recently and discussed some of the challenges that the
> team has and how we can break them down and resolve these issues.
> 
> The key challenge from what I can see is (a) the discover-ability of
> usefulness of documentation (i.e. ensuring people can find help for the
> problems they might have), and (b) how easy it is to participate in the
> docs team and contribute to documentation.
[...]
> So, I have a few proposals I wanted to share with the team to gather
> feedback on:
> 
>       * We migrate to Sumo and this be the new help.ubuntu.com. This
>         would involve a migration process (setting up a test server,
>         theming it etc ensuring that authentication with Launchpad works
>         etc).
>       * We govern the site in much the same way Wikipedia works - anyone
>         can contribute if they register an account, and the docs teams
>         helps to moderate content and contributions, and lock down
>         certain pages where required.
> 
> I believe that these two goals will result in a more useful
> help.ubuntu.com and an easier and more effective way of people
> contributing. Do you folks believe this could be a good step forward?

Certainly, but I believe that an effective solution will require more
than just a change in technology. The Ubuntu support ecosystem is
extremely fragmented in general, and replacing h.u.c and h.u.c/c with a
single system would only be a small step in the right direction.

The problem with documentation is that pretty much everyone knows how to
write... but that doesn't mean that they know how to write good docs for
end users. People look at the help, are dissatisfied with it, and rather
than trying to improve it or discuss the issue properly they just start
their own project. This inevitably runs into many of the same problems
as the original documentation and the project dies. We're left with a
confusing mess of documentation, both official and unofficial, current
and outdated, correct and incorrect, understandable and impenetrable,
spread across multiple sites and managed by different people. This is
terrible for our end users.

If we do adopt something like SuMo and use a Wikipedia-style access
model, then it's vital that we get the *whole* community behind it. It
needs to be *the* go-to place for Ubuntu help. Maintaining multiple
systems spreads the pool of contributors too thinly; we need lots of
manpower to maintain the quality of the resource, to prevent
well-meaning but uninitiated contributors from making bad changes, and
to train people so they know what they're doing. A lack of coordination
between teams leads to different support strategies which clash and
compete. We need one team managing the whole enterprise so we have a
coherent "big picture" for user assistance.

If everyone works on the same thing and has a clear set of shared goals,
we can have something like a really useful resource for users prepared
in comparatively little time. (I think we did a pretty good job of this
with the GNOME Desktop help last release cycle.) But if we just throw
yet another new website into the mix and don't think about the big
picture, it'll fail like everything else.

Politically, this might not be so easy to implement.

Thanks,

Phil