User documentation planning

[Jean Hollis Weber <je...@gmail.com>]

As many of you know, user documentation is my area of expertise. I've
been writing, editing, and publishing user guides for OpenOffice.org for
at least 7 years (probably more). I would like to discuss our plans for
user docs. I have started a page for this topic on the community wiki:
https://cwiki.apache.org/confluence/display/OOOUSERS/User+Documentation
+Plan 

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. 

Each choice, and combination of content/source/delivery choices, has
pros and cons. We certainly don't have the resources (people or, in some
cases, tools and/or skills) to produce a full range of content types or
deliver in all possible formats, but we could have a "wish list" as well
as a plan for what we are going to do over the next 6-12 months.

--Jean

Re: User documentation planning

[Jean Weber <je...@gmail.com>]

On Tue, Jun 28, 2011 at 04:39, Frank Peters <fp...@googlemail.com> wrote:
>> 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.

As I mentioned in an earlier note, OOoAuthors was set up (years ago)
because the people wanting to produce user guides found the "official"
docs project tools and website too difficult to use. This was before
the OOo wiki was set up. There is a lot of overlap between the people
on the "official" docs project and the OOoAuthors group.

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

I agree.

--Jean

Re: User documentation planning

[Jean Hollis Weber <je...@gmail.com>]

On Tue, 2011-06-28 at 05:59 +1000, Jean Weber wrote:
> On Tue, Jun 28, 2011 at 05:49, C <sm...@gmail.com> wrote:
> >
> > Last I checked, the Confluence Wiki can export to PDF and MS Word
> > documents, but cannot export to ODT.  It would be somewhat
> > embarrassing to use a Wiki for OOo documentation and only be able to
> > export MS Word formatted documents :-P  Or... can someone create an
> > ODT export extension for Confluence?
> >
> 
> I know one of the documentation team at Atlassian, who works on
> Confluence (among other products). She spoke at the Australian Online
> Documentation Conference last year about the many ways her
> documentation group was using Confluence. I believe the topic of
> export to ODT came up (I probably asked), but I don't recall the
> answer. I'll ask her if anything is happening about this.


Sorry for the delay on this. It was entirely my fault in not asking my
contact earlier; I got a response from her almost immediately after
sending a query. Here's what she said:

There is an open request for the feature on our issue tracker:
https://jira.atlassian.com/browse/CONF-4730

A good idea would be to contact the development team who provide the
Scroll Office and Scroll Wiki Exporter plugins for Confluence. The
company is called K15t. They are based in Germany. I've had quite a lot
of contact with Tobias and Stefan, both really great guys. They know a
lot about office, documentation and Confluence.

Here are their contact details:
"Stefan Kleineikenscheidt (K15t Software)" <st...@k15t.com>
"Tobias Anstett" <to...@k15t.com>

Someone else should follow up on this, as I'm unlikely to understand any
technical aspects of the reponses.

--Jean

Re: User documentation planning

[Jean Weber <je...@gmail.com>]

On Tue, Jun 28, 2011 at 05:49, C <sm...@gmail.com> wrote:
>
> Last I checked, the Confluence Wiki can export to PDF and MS Word
> documents, but cannot export to ODT.  It would be somewhat
> embarrassing to use a Wiki for OOo documentation and only be able to
> export MS Word formatted documents :-P  Or... can someone create an
> ODT export extension for Confluence?
>

I know one of the documentation team at Atlassian, who works on
Confluence (among other products). She spoke at the Australian Online
Documentation Conference last year about the many ways her
documentation group was using Confluence. I believe the topic of
export to ODT came up (I probably asked), but I don't recall the
answer. I'll ask her if anything is happening about this.

--Jean

Re: User documentation planning

[C <sm...@gmail.com>]

On Mon, Jun 27, 2011 at 20:39, Frank Peters <fp...@googlemail.com> wrote:
> 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.

Last I checked, the Confluence Wiki can export to PDF and MS Word
documents, but cannot export to ODT.  It would be somewhat
embarrassing to use a Wiki for OOo documentation and only be able to
export MS Word formatted documents :-P  Or... can someone create an
ODT export extension for Confluence?


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

I would strongly vote to keep the MW engine too.

If the push is to move all Wiki doc content over to the Confluence
Wiki, there is a lot more to the process than a simple import.  There
is a lot of customization on the MediaWiki side.. custom extensions,
tweaked extensions etc. (most of it is documented on the OOo Wiki
http://wiki.services.openoffice.org/wiki/Wiki_maintenance but there is
definitely some of it in my head that I forgot/neglected to write
down)  Added together, the tweaks and combination of extensions make a
migration to Confluence rather complicated, and it would be a lot of
work.  Best case, a few thousand pages would need complete overhaul or
rewriting to bring them over to Confluence.


C.

Re: User documentation planning

[Frank Peters <fp...@googlemail.com>]

> 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