ubuntu-manual team mailing list archive

[Kevin Godby <godbyk@xxxxxxxxx>]

Dear Documentation Team,

On behalf of the Ubuntu Manual team, we wanted to reach out to you to
start reconciling our two teams' approaches to creating great Ubuntu
documentation.

First, a word of deep respect for your work. The Ubuntu Manual Project
(UMP) would not exist without you -- we simply would not have a
userbase of Ubuntu users without the great help and support tools that
you've built over the years that helped nurture people on their path
from 'clueless newbie' to involved community members. You've also
solved a lot of hard problems related to releasing high quality
documentation, on time, release after release after release. Our
collective hats off to you!

The reason we are writing is that there's been a bit of butting heads
between the Docs Team and the UMP team. We've sometimes been too quick
to dismiss the complexity of embarking on some of our projects, while
we think that you've at times turned slightly too critical of an eye
to our 'newcomer' project.

We would like to take stock of where we all stand. Clearly, we share a
lot of goals and values. We share the goal of educating users about
Ubuntu. We all want to improve the comfort in, or the mastery of all
subjects of the OS. Both of our projects want our content be
accessible to the majority of actual and potential users worldwide. We
all want to encourage participation from the larger Ubuntu community.
And, finally, we all want to bring together duplicated efforts to
ensure a consistent voice, and a collaborative environment of people
interested in educating users.

At the same time, there are some differences in our approaches as well.

Our team feels that there are some unaddressed gaps in Ubuntu
documentation. For example, there is a lack of official linear
documentation -- a guide, hence the UMP project's manual. There is
still a lack of centrally-produced, localized documentation. There is
very little visual aid in the docs, and no focus on multimedia.

We also felt that the Docs Team's process was somewhat rigid, and too
slow for certain types of contributions. While this approach is very
consistent with the docs team's emphasis on long-term sustainability
and quality of the docs process, there was. in our view. much less
emphasis on widening the scope of documentation and simplifying
community input.

We also felt that there is a place for great tools that could be built
to help make the process of contributing much easier. This could take
the form of simplified multimedia content creation (cf. the Quickshot
tool that we built to simplify capturing screenshots in multiple
languages); it could take the form of improving our translation
infrastructure or taking advantage of collaborative editing.

Finally, and perhaps most acutely, we felt that there is a need to
create a top-notch documentation system for public help docs that can
replace the help.ubuntu.com model that's somewhat stagnated since
Hardy (witness the eerie similarity between
https://help.ubuntu.com/8.04 and https://help.ubuntu.com/10.04).

Now, and most importantly, please understand that we do not mean that
we need to start from scratch -- we do not seek revolution or
competition. We do, however, want to achieve our goals, which
hopefully means that we find a way to coordinate our work rather than
working independently.

Here's what we think is necessary for us to work well together. We
would certainly like to pursue some improvements to close the
perceived gaps in usability, focus, collaboration, etc. Some of this
may involve the creation of tools, some of this involves research, and
some involves plain old copywriting and maintenance. For the tools
portion, we would like to have specific discussions about these tools,
namely how to improve the help website, how to merge multiple projects
into a single help website, and how to more easily allow community
input into the process of writing docs. We would also like to move
forward with centrally-managed, localized documentation.

What are your thoughts on this matter? How do you think that we can
work together? We think that the solution of 'everyone join the
existing Docs Team process' is not directly workable, since it's clear
we have some cultural and procedural differences right now -- much as
having UMP just fork the Docs Team's content is a bad solution. How do
_you_ think the UMP team can improve the working relationship between
the two approaches?

Best regards,

ilya haykinson <ilya@xxxxxxxxxxxxxxxxx>
Kevin Godby <kevin@xxxxxxxxxxxxxxxxx>
Ubuntu Manual Project