ubuntu-manual team mailing list archive

[Phil Bull <philbull@xxxxxxxxx>]

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

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

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.

Thanks,

Phil

-- 
Phil Bull
https://launchpad.net/~philbull