ubuntu-manual team mailing list archive

[Jim Campbell <jwcampbell@xxxxxxxxx>]

Hi All,

On Thu, May 13, 2010 at 3:41 AM, Kevin Godby <godbyk@xxxxxxxxx> wrote:

> 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?
>
>

Hi All,

Time requires that I be brief, but I've added some notes to your wiki page
about a support and learning center [0].  Mozilla Sumo seems to cover most
all of what you've requested, and the site code is freely available.  I'd
recommend taking a look at it if things go that way.

With regards to DocBook, Mallard and sharing content via content pools, it
seems like Mallard, DITA, and Docbook have a game of rock-paper-scissors
going on . . .
- Mallard could fare well enough in a "content pool," and is supported by
Yelp (the Gnome help browser), but there is no Mallard-to-PDF transform
available at this time.
- DITA is expressly designed for "content pools," and can be output to PDF
(and HTML and epub), but yelp does not currently support DITA, and Gnome is
going toward Mallard.
- Yelp supports Docbook, and you can ouput to PDF from Docbook, but Docbook
is not particularly well-suited to "content pools."

With regards to the manual team's use of LaTeX, the output the HTML and PDF
is very good, but translations are all done manually.  Each of the other
markups shown above are XML-based, and can thus be used with existing
translation tools.

Jim

[0] https://wiki.ubuntu.com/ubuntu-support-and-learning-center#Notes