Need of a documentation framework for LibreOffice?

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.

Hi everyone,

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.

Indeed, you're right. When ready, we will post here a testing site for that
documentation framework to know yours observations, proposal and comments
about that option.

Cheers

Hi everyone,

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

What about this: Each book as a coordinator* responsible of that book. And,
each page/subpage/chapter may have a responsible too. Pages that do not
define a responsible user inherits the responsible user of it parent. This
can be implemented in Drupal as a field on the chapter edition page, hidden
when viewing it, and the we can do reports on who are responsible of. Ok,
now we know who is responsible of what chapter... now what? What we need to
do with this information? Get a notification if the book is modified... what
else?

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

You're right, always exporting or changing from one complex format as ODT to
Wiki/HTML has problems. We will check the performance of the ODT Import
module for Drupal to know what are the capabilities of the plugin. If a
correct import is done, people could work on ODT and then import them to
nodes on Drupal, so people will be able to read it online on site as a book
in many ways.

Cheers

Hi again,

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>

Talking about graphics management, I'm researching about improving the
internal links and graphics user experience with the Drupal visual editor
for the Documentation team. I done both on other projects, but never
integrate them to know how they works together. So, I have homework :stuck_out_tongue:

For Internal linking I usually use http://drupal.org/project/pathfilter
with http://drupal.org/project/linkit for a good user friendly internal
links feature.

And on the other way, I usually use http://drupal.org/project/imagebrowser for
just images or http://drupal.org/project/webfm (but this one is quite more
complex and sometimes these features tend to be overwhelming for the user,
so, if the first one work better).

I'll try to integrate all those together with the CKEditor and know how they
work. I'll need to test also the integration with the ODF Import module when
uploading files.

Cheers

Hi Carlos:

Would it be possible to tailor the CKEditor with a set of features for a particular user and another set for another. It seems to me that the documentation teams have been around for a while and would perhaps like the feature rick modules like webfm whereas others members may find it too overwhelming. Is it possible to offer the choice for users? Maybe a setting on the user side of the CKEditor could offer them a more feature rich set of buttons?

This could also be of interest to users who would have mastered the use of the main CKEditor features and would like to graduate to the more feature rich version of the editor.

Marc

Yes, it is possible. So, we would need a stripped down version of CKEditor
and a most complete one. The WebFM can be administrated with roles. So,
some roles could use it and others don't.

Checking this page http://wiki.documentfoundation.org/Website/Drupal/Roles I
think just administrator roles should be able to use it.

Cheers

Neat! Nice admin function to have.

Marc