incubator-ooo-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Frank Peters <fpe.mli...@googlemail.com>
Subject Re: User documentation planning
Date Mon, 27 Jun 2011 18:39:26 GMT
> There are three main planning topics regarding user docs:
> * Content
> * Source format
> * Delivery format
>
> These are related, but not the same. Some content may work better in
> some formats (both source and delivery) than others.
>
> CONTENT could be user guides (a term for multi-topic, typically
> book-length documents) and a range of shorter document types: how-tos,
> tutorials, FAQs, and so on.
>
> SOURCE FORMAT could be ODT or wiki.
>
> DELIVERY FORMAT could be ODT, PDF, printed, ePub, HTML, blog, wiki,
> video, etc. For electronic formats, target hardware could include laptop
> or desktop computers, iPads, Android tablets, smartphones, Kindles,
> etc.

I would like to clarify this further. At classical OOo we had the
(somewhat awkward) situation of an "official" OOo docs project
and the (then) OOoAuthor group being separate groups
working with separate people, separate tools and separate
deliverables. OOoAuthors created user guides, while the
OOo docs website and wiki was the place for Admin and
Developer docs, FAQs, some Howtos etc.

If we continue this model, I would think that the non-book
document types you listed above (Howtos, FAQs etc) would again
be located (and maintained) on the Apache OOo wiki under AL.

Also, when talking about user documentation we must also
include administrator users and developer users that are
currently served through the wiki (Admin, BASIC and Dev Guide).
Would those docs go on the community wiki or the dev wiki?

In this context, I would like to emphasize again that the
current content on the OOo wiki is *very much taking advantage
of specific Mediawiki features*. Some of those are unique to
Mediawiki (AFAIK) and we would lose some nice features if
we switch engines, for example, "living" TOCs, dynamic page
lists, and the creation of customized PDF/ODF books from wiki
content.

If there is any way of keeping MW as engine for the Apache
OOo community wiki I would strongly vote for it.

Another doc piece is application help, the current potential of
presenting a holistic docs approach by including all types
of docs (user guides, app help, faqs etc) and referencing
or reusing across is underdeveloped. App help is a beast of its
own and should not be.

Frank


Mime
View raw message