wiki vs documentation

Elizabeth Krumbach Joseph lyz at ubuntu.com
Thu Sep 19 16:22:41 UTC 2013


On Wed, Sep 18, 2013 at 11:54 PM, Jonathan Aquilina
<eagles051387 at gmail.com> wrote:
> Liz why not make it more detailed and those that need something basic can
> filter out what they need, I say that the more in the documentation the
> better. alot of the software has lots of features and if you only provide
> basic features end users might not know if there is a better features of a
> particular piece of software that they should be using.

So we still have to consider that all official docs should be
translated, and the translators have a very limited amount of time
each cycle to do this, and that we'd have to keep them all updated,
which is difficult enough right now even with the small amount of docs
we have. So even if we have chunks of "selected" docs defined somehow,
everything still needs to get translated and updated. I'm not fully
convinced that even if we leverage wiki contributors that we'd have
enough solid commitment for these tasks.

Your idea of having wiki-style supplementing the official docs is a
good one, but there are technical challenges there. Right now we
should have a policy for wiki editors to first link to the official
docs and then add their own details in the wiki, but in reality it
doesn't always work this way because the organization of the docs
confusing to a lot of people, and the official docs are strictly
versioned whereas wiki docs aren't always (they often cover several
versions). A couple cycles ago Ben looked at the software that runs
Mozilla's SUMO[0] but aside from the conversion being a massive job
that we don't have the staff for, it wasn't technically really mature
enough to be used outside the Mozilla infrastructure at that time. I'd
be personally reluctant to go down the new tech route again before we
do a proper analysis of how we can improve what we have now, as I
think it can work if we have a clearer guide for wiki contributors
about how the docs are organized, and in turn more contributors across
the board.

[0] https://support.mozilla.org/en-US/home

-- 
Elizabeth Krumbach Joseph || Lyz || pleia2
http://www.princessleia.com



More information about the ubuntu-doc mailing list