Need of a documentation framework for LibreOffice?

Hi Jeff,

first a wish from my side: please don't sent the complete email you are answering to
with your post. Because this is a mailinglist, you need only to resent the parts,
that are needed to understand your comments.

Will Drupal's book module be used for the user manuals? Or will they still
be edited in ODF then "uploaded" as the web-based documentation?

I think, we should use for the creation of user manuals the software we are
delivering to our users. We can then use our software to convert the documents to PDF
and publish them on the website. Most people don't need the odf-versions.

Regards,
Andreas

Andreas,
I do not disagree with you with the creation of user manuals in LibreOffice.
There has been no decision regarding the use of Drupal yet, but...
The Drupal book module allows the upload of ODF and PDF files as well
as copying the contents of that document into the webpage that holds
that document, in effect resulting in a version controlled html copy
of the document and file together in one official place.

This might be very useful in the future for links from the LibreOffice
help menu/system.

I think it might help in both documentation development and end user
ease of use.
Just an idea to ponder on.

Michael Wheatland (Wheatbix)
www.wheatland.com.au

Hi Andreas et al:

I am a big proponent of ODF files and as a teacher promote these to my student (grades 4-8). It would still be nice to have he .odf versions here and there to show people that the creation of these were done on LibO in a serious work environment.

But sure, .pdf would be nice.

Jeff -- re: using the Book module for the user manuals, yes we were looking into this. You could suggest another module if you had one in mind.

The sky is the limit for everything on Drupal.

Marc
I am also on the Drupal Dev Team

I'll second the proposal that both ODF and PDF files should be available
for downloading.

For most people, and most purposes, the PDFs are fine.

The virtue of the ODFs is that users can easily add additional
notes/documentation to their copy. My perception is that having the ODF
makes it slightly easier for people to grok creating and using styles.

Jeff -- re: using the Book module for the user manuals, yes we were looking
into this. You could suggest another module if you had one in mind.

The sky is the limit for everything on Drupal.

Hi Marc--this doesn't count as a Drupal module because it's an entirely
separate application, but I had purchased KBPublisher (
http://www.kbpublisher.com/) for a project I was working on several months
ago and we ended up not using it. I had purchased the "Small Biz" one. It is
a dedicated documentation application which supports a "book" type layout.
You can see a demo of it here: http://www.kbpublisher.com/kb/1/

I don't know how firm you guys are on using Drupal, but I have a license
that I am not using for this software, and I wouldn't mind donating it to
the project (I have no use for it). So, for what it's worth, it's available
for use if you guys want it.

Jeff

Jeff, as I have mentioned there has been no official decision made on
using Drupal at the current time.
As for being 'set' on using any one system, I think the vast majority
of us can agree that free open source software is the way to go.
There will be discussions within the website group as to the backbone
of this once the workflow and other requirements are set.
Thanks heaps for the offer!

Michael Wheatland (Wheatbix)
www.wheatland.com.au

Hi everyone,

I'm also on the website team,

The workflow diagram would be great in order to kick off discussions
 about implementation. Also a description of the structure of the
 responsibilities and permissions required for doc development would be
 great.

This is a most have, thanks for pointing it out.

The Drupal book module allows the upload of ODF and PDF files

Ok, with the Upload module.

as well as copying the contents of that document into the webpage that holds
that document,

I didn't know that :smiley: How can this me done? To had that requirements
(modules/tweaks) to the wiki.

in effect resulting in a version controlled html copy
of the document and file together in one official place.

+1 with the Diff module.

Cheers

Hi everyone,

Hi Marc--this doesn't count as a Drupal module because it's an entirely
separate application, but I had purchased KBPublisher (
http://www.kbpublisher.com/) for a project I was working on several months
ago and we ended up not using it. I had purchased the "Small Biz" one. It

is

a dedicated documentation application which supports a "book" type layout.
You can see a demo of it here: http://www.kbpublisher.com/kb/1/

Free software using not-free software.... mmm I'm not sure this is the kind
of message LibreOffice want. But thanks for your offering.

Drupal is quite strong, the demo site you showed help me out to go search
this functionality.

After two hours investigating :S I did found something similar:

http://drupal.org/project/booktree

And the demostration here:

http://uccio.org/booktree

As it is a list, it is easily styled.

I did also found this other helpful modules:

This will help allowed users to modify the outline of a book easily:

http://drupal.org/project/outline_designer

Adding this other two:

http://drupal.org/project/flat_book
http://drupal.org/project/tableofcontents

Will could get a nicely book ready to get printed:

http://drupal.org/project/print

Or using the export feature of the book standard module.

:smiley:

Hi everyone :smiley:

> as well as copying the contents of that document into the webpage that
holds
> that document,

I didn't know that :smiley: How can this me done? To had that requirements
(modules/tweaks) to the wiki.

Found it :smiley:
http://drupal.org/project/odfimport

So cool :smiley:

Cheers

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.