ubuntu-manual team mailing list archive

[Phillip Whiteside <phillw@xxxxxxxxxx>]

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.
Hi,

Can I give a +1 for use of images, one of the ones I was interested doing
was installing LAMP, in the meantime, there are people having problems, the
sooner a couple of simple screen-shots can be included the better. I was
going to do a 1 hour presentation on it, except that it takes all of 10
minutes to do.

Yes, we do have to make allowances for those who do not have internet access
speeds / limits to allow the downloading of many images, so we must bear
those in mind. Can the docs team also have a look at Rule508 that does
require an explanation is put into the <alt tag> ?

http://www.section508.gov/index.cfm?FuseAction=content&ID=12#Web

That will, possibly drag all the documentation together.

I've cc'd this discussion to the accessibilty mailing list, as I have not
seen any mention of it and I do think it is important that these needs are
considered.

Just my $0.02

Regards,

Phill,


On Sun, Jun 13, 2010 at 12:16 AM, Phil Bull <philbull@xxxxxxxxx> wrote:

> 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
>
>
>
> --
> ubuntu-doc mailing list
> ubuntu-doc@xxxxxxxxxxxxxxxx
> https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
>