[odfauthors-discuss] user guide for large complex documentation with Writer

Forwarding this to a more appropriate discussion list. --Jean

Hello Roger

Comments below.

Forwarding this to a more appropriate discussion list. --Jean

From: Roger Caws <polysult@hotmail.co.uk>
Date: Tue, Apr 19, 2016 at 8:32 AM
Subject: [odfauthors-discuss] user guide for large complex
documentation with Writer
To: odfauthors-discuss@lists.odfauthors.org

Hello,
This is me
1 Experienced documentation author and project manager
2 background is large complex documentation using Word Perfect and
Microsoft office in a windows environment
3 disenchanted with Microsoft quality and direction.
4 recently switched to Linux Mint with zero knowledge of Linux
5 used lots of tutorials, on-line manuals etc with mixed results
6 Most of what is out there assumes a) a knowledge of Linux and its
quirks; b) that the reader wants to know just enough for simple
documents.
6 decided that best way to learn how to use LibreOffice is by writing
a manual for Writer (complex projects)
7 Have firmed up on design which has three components
a) A manual which covers "how to" of ALL the facilities in Writer (and
actually uses as many of them as possible)
b) A construction history which details how this particular manual was
developed and how to use it as a start point for other documents which
use a lot of the facilities of Writer (and assumes that the reader has
limited experience of manual development)
c) A section showing alternative settings and results for design so
that the reader is not restricted to choices made for THIS manual

This is my Questions
1 Would the existing authors organisation welcome such a project or
regard it as an impertinence.

No impertinence. All projects and efforts are welcome, but there is
little to gain with repetition of work if resources are in short.

We already have a set of books on LibreOffice: In-depth module guides
and a Getting Started guide. They were written with the best practices
in word processing (we taste our own dog food). These books however need
update to the latest version of LibreOffice, and this is a large
project per se. We also have a process of authoring books on LibreOffice
that is documented as well.

But books and processes are not carved in stone, never. We will
appreciate your experience and advise on how to improve our content and
processes.

2 This will be a non-trivial document and I would welcome more
knowledgeable input given my own weakness in this area. Could this
happen and how would it work?

Our documenting process is available in ODF Authors website

http://www.odfauthors.org/libreoffice/english/resources-for-contributers

We will be glad to know your thoughts on it.

ODF Authors has many books awaiting to be updated to release 5.1 of
LibreOffice. Some are as old das version 3.x.

One important note: Our LibreOffice books are source for many
translations worldwide. Our processes and content must consider this fact.

Write me offline if you need an login for ODFAuthors.

3 It is going to take some time so how would new releases be
incorporated so that it was up-to-date when released

Software development is not tied to documentation avaliability. We lag
here. But with resources, it is perfectly possible to have books and
software synchronized at launch date.

The project still has a primary purpose of ramping up my learning
curve to the point where I can undertake other similar complexity
projects with confidence.

By joining our doc team you will gain a lot of experience and share your
own with us.

I am not aware of anyone actually publicly documenting a documentation
project previously so it should be quite an interesting thing to do.

Please look at the "resources for contributors" in ODFAuthors.

I look forward to your comments

Kind Regards
Roger Caws

Thank you for your contact. We look forward to have you in our team.

decided that best way to learn how to use LibreOffice is by writing a manual for Writer (complex projects)

Are you married to the idea of writing documentation for Writer?
If not, I'd recommend writing documentation for Draw, Impress, Base,
Math, or Calc.

a) A manual which covers "how to" of ALL the facilities in Writer (and actually uses as many of them as possible)

All?
Depending upon how LibO is configured, functionalities, and facilities
appear and disappear. This applies even if no additional extensions are
installed.

2 This will be a non-trivial document and I would welcome more knowledgeable input given my own weakness in this area.

I wonder if you realize just how huge a task it is, to document all of
the functionality in even one component.

jonathon

Roger may not be subscribed to this list, so he may not be seeing the
responses. --Jean