Need of a documentation framework for LibreOffice?

Maybe the drawing I created some time ago[1] (according to the
description given from Jean resp. the oooauthors list) can be helpful
for discussion. Feel free to use or change it. Note, that it may be
inaccurate or outdated.

Verbal description (AFAIR):

There are 2 main workflow pathways: A simple one for internal documents
and another one leading to externally published documents.

The internal path only has 2 states: draft & published internally.

The external path includes 3 different document states:
internal draft,
pending review (which means, submitted for publication),
published externally.

Transitions are, of course, submission, publication, and retraction (the
latter leading back to draft state[?])

L10N: Documents from any state might give rise to translation
activities, which again would open the same (or a similar) workflow for
the (now localized) document.

The main 2 problems in the (folder based) Plone system IMHO was to find
a document (where is the newest version?) and to get a quick overview
over the project state (how many documents are in which state, how many
untranslated documents, etc.). Hence, keeping track over the project
had to be done mainly by a human (i.e. Jean :wink: ).

Also missing are "minor" state informations e.g. "checked for software
version X.Y" or "indexed" or "branding updated" or similar (which is a
minor point but nice2have, and could be done e.g. by tagging).

Nino

[1]
http://wiki.services.openoffice.org/wiki/User:Nnino/Drafts/Oooauthors_Workflow

Thanks for the help Nino. We will also take a look at this.

Marc

Maybe the drawing I created some time ago[1] (according to the
description given from Jean resp. the oooauthors list) can be helpful
for discussion. Feel free to use or change it. Note, that it may be
inaccurate or outdated.

Nino, thanks for posting this. Not only does this illustrate the challenges of creating / updating documentation (which others may or may not be aware of), but it may also give us time to reflect on this process and see if there are solutions available that could at least help make it slightly less tedious.

- Gabriel

Yes, and if you leave your comments on this thread, we will look at this from the point of view of a Drupal website. We will tailor it to your needs. We can make it work the way that you want.

Marc

Hi everyone,

Thanks Nino, that's just great.

> Thanks, I'll take a look. Is there anyway that someone on the
> documentation team to sketch out the workflow. You have developed
> this over a few years and we don't really have a workflow to work
> with. This would help to demistify workflow.

Maybe the drawing I created some time ago[1] (according to the
description given from Jean resp. the oooauthors list) can be helpful
for discussion. Feel free to use or change it. Note, that it may be
inaccurate or outdated.

Verbal description (AFAIR):

There are 2 main workflow pathways: A simple one for internal documents
and another one leading to externally published documents.

The internal path only has 2 states: draft & published internally.

The external path includes 3 different document states:
internal draft,
pending review (which means, submitted for publication),
published externally.

Internal published documents are owned by (who can edit it) a user, a open
group or a closed group (membership)? What is the difference between users
who can edit/create internal documents and those who can edit/create
externally published documents?

Transitions are, of course, submission, publication, and retraction (the
latter leading back to draft state[?])

L10N: Documents from any state might give rise to translation
activities, which again would open the same (or a similar) workflow for
the (now localized) document.

The main 2 problems in the (folder based) Plone system IMHO was to find
a document (where is the newest version?) and to get a quick overview
over the project state (how many documents are in which state, how many
untranslated documents, etc.). Hence, keeping track over the project
had to be done mainly by a human (i.e. Jean :wink: ).

Also missing are "minor" state informations e.g. "checked for software
version X.Y" or "indexed" or "branding updated" or similar (which is a
minor point but nice2have, and could be done e.g. by tagging).

No problem, this can be done with "Taxonomy" feature within Drupal. Also
with "Views" we can generate reports on that information. What kind of
reports would you like to have?

- List of internal documents, ordered by date. (each document, "node", as
revisions, so no problem, almost like a wiki).
- List of internal documents, grouped by workflow state.
- List of internal documents, filtered manually with terms (published for X,
Y, etc).
... What more?

I really think we are going to need a Dashboard on the website so users
can accommodate their work or interest on their dashboard.

Cheers

Note/Question: Should I cross-list?

Another question that needs to be asked, should we have a document
checkout for the workflow to ensure that only one person is working on
any given document at once?

Also how is community consensus reached as to when a document is ready
for external publishing?
A democratic review system for proposed changes on final review
documents should be pretty easy to setup (Voting API). For an example
on this type of system have a look at Ubuntu Brainstorm, slightly
different concept but could work just as well.

Thanks for the info so far.

I really think we are going to need a Dashboard on the website so users
can accommodate their work or interest on their dashboard.

Cheers

Note/Question: Should I cross-list?

Another question that needs to be asked, should we have a document
checkout for the workflow to ensure that only one person is working on
any given document at once?

The current setup has a "flag" that is set for "retract" to show that someone else is working on the document, though it does not prevent someone else from downloading.

Also how is community consensus reached as to when a document is ready
for external publishing?
A democratic review system for proposed changes on final review
documents should be pretty easy to setup (Voting API). For an example
on this type of system have a look at Ubuntu Brainstorm, slightly
different concept but could work just as well.

Thanks for the info so far.

There is no community consensus on when a document it ready for external publishing. Right now, Jean Weber, the volunteer co-lead makes that call. I see no problem with this setup as Jean has the expertise to make the call, and I have seen no complaints from any other members. I do not feel a vote would be in the best interest of the project.

Have a look at the www.oooauthors.org , on the entry page is a dcoument called Introducing OOoAuthors it details how the project works.

Andy

Although people seem happy with me acting as "publisher" for the OOo
user guides, it really would be much better if each book had its own
coordinator/editor/publisher, both to spread the work around and so
people could cover for each other if someone is unavailable for more
than a few days (illness, travels, other work or family commitments).

The idea was to have an experienced technical editor (or similar) to act
in the role of coordinator/editor/publisher for each book, but the other
people who filled that role in the early days have moved on to other
things.

BTW, the OOo *developer* docs are not handled through OOoAuthors; those
docs are primarily wiki-based and the processes for review and approval
are different.

--Jean

There is no community consensus on when a document it ready for external publishing. Right now, Jean Weber, the volunteer co-lead makes that call. I see no problem with this setup as Jean has the expertise to make the call, and I have seen no complaints from any other members. I do not feel a vote would be in the best interest of the project.

Have a look at the www.oooauthors.org , on the entry page is a dcoument called Introducing OOoAuthors it details how the project works.

Although people seem happy with me acting as "publisher" for the OOo
user guides, it really would be much better if each book had its own
coordinator/editor/publisher, both to spread the work around and so
people could cover for each other if someone is unavailable for more
than a few days (illness, travels, other work or family commitments).

I agree that this would be a big help all the way around. :slight_smile: My main point being that a community vote, to me, was not the way to go.

The idea was to have an experienced technical editor (or similar) to act
in the role of coordinator/editor/publisher for each book, but the other
people who filled that role in the early days have moved on to other
things.

If we can find those with the experience needed.

BTW, the OOo *developer* docs are not handled through OOoAuthors; those
docs are primarily wiki-based and the processes for review and approval
are different.

I knew that I had not seen any of the developer docs on the OOoAuthors site, so that is why.

Andy

Hi Jean

Thanks for your answers and all of the other documentation team answers. This is really a lot of good information. If only there were enough members to do all that we wanted. Let's hope that with LibO more people will come on-board for help with the documentation team. I am guessing the the US and Canadian have not really been tapped and I am also guessing the Mexico is probably the same. Once we organise and market we will hopefully get more people on board.

Could you tell me (I am also a the LibO Marketing Team member) how many more members you would need at this point, what type of qualifications they should have? Ideally, how many would the documentation team need?

Also do you know if the developer docs have a workflow page and could you point me to this page?

Thanks again for all of your help. As you can tell the Drupal team members are here to listen and to help out. Let us know if there are any missing features that the documentation team would like to have or if you would like a change in the workflow in the Drupal setup.

Cheers

Marc

Hi Jean

Thanks for your answers and all of the other documentation team answers.
This is really a lot of good information. If only there were enough
members to do all that we wanted. Let's hope that with LibO more people
will come on-board for help with the documentation team. I am guessing
the the US and Canadian have not really been tapped and I am also
guessing the Mexico is probably the same. Once we organise and market we
will hopefully get more people on board.

We actually have a lot of volunteers at OOoAuthors, but only 10 or so of
them do much of anything. Most of that 10 do excellent work (mainly
editing and reviewing, but also some writing) but they are not available
as much as is needed.

Could you tell me (I am also a the LibO Marketing Team member) how many
more members you would need at this point, what type of qualifications
they should have? Ideally, how many would the documentation team need?

Ideally, for the user guides we need 5 coordinator/ editor/ publishers
(I don't really know what to call them) -- 1 for each book -- and I
don't know how many doing the writing/ editing/ reviewing/ indexing/
graphics. I would like to see each chapter have someone taking
responsibility for keeping it up to date, though obviously one person
could take on several chapters, either in one book or a series of
related chapters in several books: for example, all the chapters on
customizing or all the chapters on printing & PDF creation. That would
maximize consistency with the least effort. So... maybe 20 people? (And
I'm not considering other types of docs, such as FAQs, tutorials,
how-tos, etc.)

This page has more info than you want, but one relevant part is the list
of things we do when publishing a chapter or a book. There is a lot of
post-processing related to where the files are put, wikifying them, etc.
Even if much of this can be (semi-)automated, someone has to start the
process and verify that it has completed correctly.
http://wiki.services.openoffice.org/wiki/Documentation/Dashboard/Producing_User_Guides

I don't care about qualifications as such, but volunteers really need
some basic skills that are often lacking but can be highly developed in
people with no formal quals.

<aside>
Most volunteers say they will "proofread" but what we need most is
people to do research, write, and critically review/test what others
have written. Cleaning up the English when the facts are wrong isn't
much help.

Much of the work requires good analytical & problem-solving skills or
else it's done too superficially and misses too many errors, omissions,
and important inconsistencies (such as, does the figure actually show
what the text says it shows? If not, which is wrong? Are the
instructions complete, correct, and written at an appropriate level for
the audience?), not nitpicking over fine points of grammar or word
choice.

Technical writing/ editing/ indexing/ graphics experience can be
valuable but IMO is not necessary. Also, many people with weak skills in
English make excellent reviewers/testers and often good writers (though
they need to be teamed with an editor) -- because they can do research,
organize the material, check facts, etc.
</aside>

Also do you know if the developer docs have a workflow page and could
you point me to this page?

I don't know, sorry. Someone who has worked in that area might know.
Clayton (the other OOo Docs Co-Lead and an Oracle employee) oversees
that area. I do know the developer docs are wiki-based and are edited by
a variety of people. I have no idea how much updating is needed.

Oh, and there is the Installation Guide, which has sort of been taken
over by OOoAuthors so should probably be considered as another "user
guide" needing someone to be responsible for it.

Hi Jean:

Thanks for the answer. A lot of things to keep track of.

Maybe Carlos could take a close look at your response here and see if his list of Drupal modules complement your working needs. It sounds like the documentation could all fit in well on the Drupal site. There will obviously be a short learning curve and one of the Drupal dev may have to lend a hand for a while till the website team has tweaked the site to your needs.

I've already come back twice to this response and still can't imagine how well you and the documentation team have done with such a load. Congrats to all of you.

Marc

I am a member of the JoomlArt template club--I'm more than happy to donate a
Drupal template if you guys want one.

http://www.joomlart.com/drupal/themes

What is the order in which documentation will be published? Will it be
created in ODT documents first, then the information is published to the
website/wiki?

This indeed has been the case for the User Guides, while developer docs
were created often first/only in the wiki.

But we will see how people will decide to work here.

For me it seems nice to have both or all three options available as some
people love to work with wiki while others prefer ODT.

As for the website, this has been in some teams used only as download
container for ODT and PDF documents. As far as I have understood Drupal
discussions so far, it's possible to write books and chapters directly
in Drupal, so this opens up a third possibility which should be
explored, too.

so we have:
odt -> pdf
     -> web &/or wiki
wiki -> odt -> pdf
     -> web
web -> odt & pdf
     (wiki is not needed in this case in my eyes as wiki is just
     a quick web)

But maybe other people have different opinions?

Nino

Some comments from my (limited) experience:
wiki -> odt generally produces a poor result even when a good template
is applied IF the material includes a lot of graphics, as in the user
guides. Much manual tweaking is then required to end up with an
attractive, well laid out odt to convert to pdf.

Starting with odt and then outputting to other formats generally works
well, IF the odt is created using an appropriate template and layout
rules. However, some of the layout in the current OOo books does not
work when output to HTML and some is a bit messy when output to wiki
format. Post-processing may clean it up, but more manual intervention
may be necessary. I have not found time to rework the layout and
template to avoid (or at least minimise) these problems. I should have a
list somewhere of the specific problems I've noted; I'll try to find it.

This is something to consider --and test-- when deciding which output
formats and layouts are wanted.

--Jean

Here is the info on how the developer docs are handled at OOo:

- Clayton monitors the Admin, Basic, and Dev guides for edits.
Depending on who made the edit, he will either just leave the edit as is
(if it's from a known contributor) or validate the edit (if it's from an
unknown contributor).

- With each release of OOo, he reviews the edits on the Basic and Admin
guide. The Dev guide will only get a cursory review due to its size.

- There currently is no publish cycle for the Dev Guide... mainly due
to its size (+/- 2000 A4 pages)

- With each _major_ release, Clayton packages up the Admin Guide and
Basic Guide in ODT and PDF formats - he generally doesn't do this for
point releases. The Admin Guide and Basic guide have, historically, been
translated by Sun (into about 6 other languages), so part of the
release process included preparation work so that the Sun translators
could extract the Wiki content and translate it.

- The community contributions for the Dev Guide are different from
the contributions for the User Guides. The Dev Guide is more or less
a collection of concepts, not a book you want to read from cover to
cover. In the Dev guide, the contributions come almost 100% from
Sun/Oracle developers. External contributions are rare.

So, there's not much of a release process in place. The nature of the
development documentation is that it's a continuous evolution, and
not so fixed to each specific release of OOo.

--Jean

Thanks for the help with this Jean. We will take a close look at this as well. It is always nice to get this type of feedback/information by an obviously interested and well-informed individual.

Many thanks again for this information.

Marc

Thanks for the insight. From what I read on the documentation mailist is that, most are interested in keeping the ODT format central to the workflow format and output, which to me is great. I have seen some grumblings here and there who have suggested other methods, perhaps for the sake of expediency, dropping the ODT format in cases such as these.

Always important showcase the ODF in this way. Thank you for giving it the importance in your workflow that it deserves.

Would it be correct for us to point to the LibO documentation process as an example of the ODF being used in a real corporate-style endeavour? We could, for example use it this way, for marketing purposes, as a working example for individuals/corporations to examine for adoption/migration considerations.

I am looking at this from a marketing point of view.

Marc

Thanks Jeff,
I will cross post this to the website list.