← Back to team overview

ubuntu-manual team mailing list archive

Re: Docs Team and Ubuntu Manual Project: Toward future cooperation


Hi guys,

I'm back from my break now. Where did we get to with this discussion?
Did the planned meeting occur, and if so, are there any logs that I can

I'll reply to a couple of points that were made a while ago.

On Tue, 2010-05-18 at 08:10 +0100, Matthew East wrote: 
> > 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.
> As I said quite early on in the last release cycle [1], I can see a
> market for a single printable manual. We tend to make a clear
> distinction in documentation writing between linear manuals and
> onscreen help - they are two very different formats with separate
> uses. But both of them have a place in helping users in different
> contexts and situations. My problem with the manual team's work hasn't
> been their goal of producing a single linear piece of documentation,
> but rather it's been the fact that the team has sought to reinvent the
> wheel by writing content from scratch, in circumstances where
> ubuntu-doc's material was essentially suitable, with modification,
> improvement and customisation, to being reused.

I agree that both linear and topic-based docs can be useful, but I don't
think any of us have a good enough idea of where we should be using
either of them. It's true that there are situations where one form of
documentation is a more sensible choice than another. But are we
actually choosing a documentation format because it's the right fit for
a given situation, or just because we feel like using that particular

I think we need to work harder on understanding our users' needs. I
don't think statements like "I can see a market for X" or "there is a
lack of Y" are helpful on their own - show me the evidence of a market
for X, or the adverse impact of the lack of Y, please!

> > There is
> > still a lack of centrally-produced, localized documentation. There is
> > very little visual aid in the docs, and no focus on multimedia.
> As to the second sentence, we have discussed many times, most recently
> in the past release cycle [2], the use of screenshots in the
> documentation. My personal view tends to be that the difficulties of
> arranging for translation of the screenshots (because it can't be done
> through Rosetta) has meant that using them is undesirable. However, if
> a way can be found to facilitate translation of screenshots, then that
> may be a way to resolve the problem.

The ubuntu-manual guys have been very successful in getting screenshots
into the docs. It's a lead that ubuntu-docs should follow, so long as we
don't go overboard and start (over-)using screenshots in inappropriate
places. I think we should work on cracking this particular issue once
and for all this release cycle.

> > 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.
> Lowering the barrier to entry and improving community input is
> definitely a key goal of every Ubuntu team, including ubuntu-doc.
> While we have made some progress towards (for example) encouraging
> people to submit material in plain text, we've clearly not done enough
> on this front. I think that ubuntu-manual has shown how to attract
> contributors by using a lot of publicity and clear instructions about
> how to contribute, and I think this is something that ubuntu-doc could
> definitely learn from. I think the major problem is that the team
> members frequently don't have much time to promote the team on blogs,
> microblogs and websites, and equally sometimes potential new
> contributors don't get as much attention and encouragement as they
> deserve. ubuntu-manual's enthusiasm could help with that.

I can work on improving doc team "outreach" over the summer, because
I'll actually have some free time over the next couple of months! I'll
start a thread on this at some point.



Phil Bull

Follow ups