Installation usability testing

[Gervase Markham]

On 06/04/09 18:11, Max Kanat-Alexander wrote:
> I agree that it should be easier to edit the docs. I do want to keep the
> following features of DocBook, however:

I don't think any of these are impossible in principle...

> 1) Localization. We just changed the directory structure of the docs to
> allow localization, so it'd be nice to keep allowing that whatever we
> decide.

MDC manages this, so I'm sure it can be done.

> 2) Different docs for different branches.

This is a good question. Has anyone come across a wiki which has good 
branching facilities?

> 3) (This isn't required, but it's nice.) Different formats, like text,
> PDF, etc.

Is there anyone who would read a text version of the install doc in 
preference to the HTML these days?

Wikipedia has, I just noticed, a PDF export function (which appends the 
entire GFDL to a 3-line article :-) so again, this is certainly possible.

> There are lots of tools and processes that the Fedora Docs project has
> developed that might be able to help us out, but first we have to move
> to having our docs compile with xmlto instead of jade.

Are Fedora Docs kept in Docbook, then? Can you tell us more about these 
tools?

> We might be able to consider adopting a commit-then-review policy for
> certain committers, on the docs. We'd want to be sure of their language
> skills, their knowledge of Bugzilla, and their technical documentation
> abilities, first.

:-) Of course, this involves a certain amount of trust. There are many 
people who know a lot about one bit of Bugzilla but very little about 
other bits. Having just done a Unix install, I'm freshly familiar with 
that, but probably wouldn't be able to update the Bugzilla Security 
section other than improving the clarity of the English or by checking 
facts. One would have to trust people not to edit docs to change things 
they didn't know about. But I'm sure that would be fine. Social controls 
are better than technical ones.

Another thing we might try is a "documentation conference call" or IRC 
meeting or similar collaboration. Several people all work on different 
bits of the docs at once, being present to answer questions from others 
like "er, is it still true that...?", then review each other's work 
there and then, and suggest improvements. A sort of "code sprint" for docs.

Gerv
_______________________________________________
dev-apps-bugzilla mailing list
dev-apps-bugzilla at lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-apps-bugzilla