How about creating manuals in mediawiki (and then export to odt and pdf when required)?

I'm probably the only other person here to say this, but I agree with
Narayan on how initial documentation should be developed. I work for a
rather large county government and all of our documentation is developed and
maintained on our intranet website. All of our documentation is web-based,
and only once a year do we export the data and create publishable user
guides for training and archival purposes. We've always found it easier to
use a web-based documentation platform to collaborate, create, edit, and
publish documentation because the documentation will always be up to date.
Plus, our users only access this documentation via the intranet website so
there is no need for them to search through multiple physical documents.
Plus, I think users would rather find all the documentation on a searchable
website than to download ODT/PDF files.

I understand the desire to create these ODT files since it's an intuitive
method to showcase the capabilities of LibreOffice, but I believe our time
could be better spent creating an up to date support site where any of us
can edit the documentation. Then, maybe once a year, the data can be
copied/exported to ODT as a printable, hard copy of the documentation.

I know most people here will disagree with me, but this is just my $0.02.

Jeff

Please see an earlier note from me on all the reasons why this would not
be an efficient way to do it at this point, including the fact that we
already have a large body of OOo info that can be readily adapted to
LibO, and that OOo info is in ODT format.

Whether users would rather find info on a website or in downloadable
file depends entirely on the users, and that depends a lot on the
product and the level of knowledge and experience of the users of that
product. My work at OOo suggests that a large number of ordinary users
prefer PDFs that they can print out. Others, of course, prefer
web-based.

I am also highly dubious that more actual work would be done on the user
guides if they were on the wiki instead of in ODT. That has not happened
at OOo; there, the writers, editors, and reviewers overwhelmingly prefer
to work in ODT, and many of them (including me) are actively unwilling
to edit on the wiki. Of course, LibO documenters may be different.

--Jean

Isn't it a good idea to use LibO to describe how to use it? :wink:
I have been translating OOo guides and learned a lot about the software by using it.

Actually I agree there! :slight_smile:

I have logged more than 300 bugs/suggestions at OOo issue tracker (Some of you may know me as "Raindrops" for last 7 years).
Notably, the pdf export features were developed in response to my suggestion.

But most of the other issues (mostly usability issues) remain open to this day
(or closed under phony reasons; like "please split this in two different issues -> Closed").

Note that "ease of writing the manual" is the goal, not "learning Libo while doing it". :slight_smile:

Having said that, Jean has raised many valid points which I faced (and solved for myself).
I will talk about what solution I've found in his separate thread.

-Narayan

I would like to pursue this line of thought a bit further. How do you
propose to start the process? From scratch, or from the existing OOo
docs? If from scratch, why?

If from the existing OOo docs, then are you saying they should be
wikified before people make the LibO-specific changes? Wikifying
existing docs is a lot of work, so it seems to me that the first step
should be updating the content of the existing ODTs and then wikifying
them. After that, maintenance could occur on the wiki, as you suggest.
Personally, I don't think that is a good idea for reasons I stated in
previous notes, but the group could choose to go that way.

IMO for the first release of LibO, ideally we would have PDFs and
printed books available, as well as info on the wiki. Started from the
ODTs is the fastest way to do all of that. For future releases, the
method could be quite different.

--Jean

This was discussed here earlier. For OOo/LibO user guides (docs aimed at

IMO for the first release of LibO, ideally we would have PDFs and
printed books available, as well as info on the wiki. Started from the
ODTs is the fastest way to do all of that. For future releases, the
method could be quite different.

--Jean

Thanks Jean for bringing out this perspective.

Yes, I agree: If the Libo docs are adopted from the well-formed docs of OOo, then there is no point in wikifying.
And I doubt if we will need any additional documents (because OOo already had a full set, from where we are starting off).

Well, that's valid only the current version: If Libo is to be "extensively re-written for contents, and not features", we may need new docs.
Then using a wiki makes sense for a fresh document.

Comments interleaved below. --Jean

*************************
Hi Jean,

@points 1-3:
prediapress is running a successful "Print-on-Demand" business out of printing books from wikis.

(see their massive catalog here: http://pediapress.com/books/)

Each book is nothing but an exported pdf from wiki.
(In fact, all those exported pdfs are available for download free of cost at PediaPress site).

So professional formatting in exported pdfs may not be an issue.

Do these books have many illustrations, tables, and other features, or
are they mostly words and/or code samples? Wiki info that is simple can
be exported easily and with good results. Wiki info that is not simple
can look very amateurish and ugly when exported. If Pediapress can do a
good job with the OO/LibO user guides, then that is great. But I'll
believe it when I see it. (I don't have time to look at any of the books
in their catalog to see if I am wrong.)

BTW the default setting of the extension is to export pdfs meant for black-n-white PRINTING.

(all text color is stripped, and links are converted to footnotes so that reader can read them).

However, PediaPress shared with us some 12 tweaks that produce pdf files meant for reading on screen.

(The exported pdf has full color text/images, and we can click on its links to jump to another "marked destination"/URL.)

Unfortunately in case of ReNamer, we have a shared server, so those tweaks could not be used.

(The changes will affect all other users too.)

But I do have a list of those config changes, which I can share if people are interested.
(Basically some parameters are changed in a few Python files at server).

No harm in trying! :slight_smile:

@point-4:
Wiki has built-in DIFF tools to see any version vs any older version.
You can roll back with a single click.
Even changes in images are tracked.

I have not seen DIFF tools that give detailed enough change tracking.
And rolling back removes ALL the changes made from one time to the next.
Usually when checking edits, I find that some need to be accepted and
others rejected. If there are tools that allow this, I would like to
know.

BTW these discussion pages are not suitable for intensive proofreading (where multiple people are commenting simultaneously).
Reason: They have to keep a track of what the OTHER critiques are saying.
This is really strenuous, because you have to open the relevant page of the odt and visualize each comment.
Rather than 10 reviewers pouring through their 10 odt files to track each-others' comments, using a wiki is far simpler.

OOo/LibO has tools to combine all those reviewers' changes into one
file. And the day I find more than 1 or 2 people reviewing and
commenting on the same document, I will rejoice!

--Jean

I think the best way to start the process would be to copy the completed,
published LibO documents. I wouldn't start from scratch since all of the
work has already been compiled and only minor changes are required to
convert the documents from OOo to LibO. But I wouldn't start the transition
until version 3.3 of the LibO documents have been published.

I agree that the first transition to a wiki would take some time, but I
think it would be worth it in the end. Would this documentation be in a wiki
format or would it be in the form of articles on the Drupal site? Or is that
thinking too far in advance?

The only reason I'm against putting all the effort into ODT documents is I
don't think it is the _best_ medium to provide documentation to the users.
Do we have any statistical data detailing user opinions on
their preferred medium of documentation delivery?

> IMO for the first release of LibO, ideally we would have PDFs and
> printed books available, as well as info on the wiki. Started from the
> ODTs is the fastest way to do all of that. For future releases, the
> method could be quite different.
>
> --Jean

Thanks Jean for bringing out this perspective.

Yes, I agree: If the Libo docs are adopted from the well-formed docs of OOo, then there is no point in wikifying.
And I doubt if we will need any additional documents (because OOo already had a full set, from where we are starting off).

OOo does not have a full set of user guides. The Base Guide has only 3
chapters in draft (which IMO need a LOT of editing), with another
chapter being worked on.

That could be a good book to try out the wiki for writing & reviewing.
LibO could take the lead on that book.

Well, that's valid only the current version: If Libo is to be "extensively re-written for contents, and not features", we may need new docs.
Then using a wiki makes sense for a fresh document.

******
Another important thing to note: All of us agreed that OOo cannot easily export an odt file to wiki.

It works better than going the other way, unless there are tools that
can handle layout complexity (see my response to your other note).

Does it not strike you as a valid development target for LiBo?

It's valid. If the problems of output from wiki and editorial change
tracking can be resolved, AND if those interested in contributing to
documentation (and skilled enough to do a good job) are willing to do
the work on the wiki, then it could work well.

--Jean

Jeff, thanks for that clarification. Some comments interleaved below.
--Jean

I think the best way to start the process would be to copy the completed,
published LibO documents. I wouldn't start from scratch since all of the
work has already been compiled and only minor changes are required to
convert the documents from OOo to LibO. But I wouldn't start the transition
until version 3.3 of the LibO documents have been published.

Okay, we're in agreement there.

I agree that the first transition to a wiki would take some time, but I
think it would be worth it in the end. Would this documentation be in a wiki
format or would it be in the form of articles on the Drupal site? Or is that
thinking too far in advance?

I believe this is still under discussion.

The only reason I'm against putting all the effort into ODT documents is I
don't think it is the _best_ medium to provide documentation to the users.

Just to be clear: I don't think ODT is the best medium for providing
docs to users, but I do think it is the best medium to use as the source
documents from which a variety of outputs (PDF, wiki, print, other) can
be derived, thus providing for the needs and preferences of a range of
users.

Do we have any statistical data detailing user opinions on
their preferred medium of documentation delivery?

I don't think so. Anecdotal evidence only. IMO no one medium will make
everyone happy, because of the wide range of age, experience, computer
sophistication, etc among users of office suite software.

One thing that could, and should, influence decisions on how to deliver
docs (not how to produce them) is: what audiences is marketing
targeting? If marketing is targeting mainly web-savvy groups such as
students, then the primary delivery mechanism for information can, and
probably should, be different from what might be best for a more diverse
or less-savvy audience.

The audience segments that I am most familiar with are, typically, not
comfortable doing web lookups (regardless of the format the info is in
once they find it) and often do not have a reliable, easy to use,
affordable connection to the web. These audience segments include small
businesses, small volunteer organisations such as church groups, and
seniors (btw, there is a fair overlap between these groups). People in
these groups very much need free (in both senses) software, but their
information-gathering methods are very different from, say, students or
people in in larger businesses.

--Jean

-----
Jeff Prater

On Fri, Dec 3, 2010 at 11:30 PM, Jean Hollis Weber <jeanweber@gmail.com> wrote:

Just to be clear: I don't think ODT is the best medium for providing
docs to users, but I do think it is the best medium to use as the source
documents from which a variety of outputs (PDF, wiki, print, other) can
be derived, thus providing for the needs and preferences of a range of
users.

> Do we have any statistical data detailing user opinions on
> their preferred medium of documentation delivery?

I don't think so. Anecdotal evidence only. IMO no one medium will make
everyone happy, because of the wide range of age, experience, computer
sophistication, etc among users of office suite software.

One thing that could, and should, influence decisions on how to deliver
docs (not how to produce them) is: what audiences is marketing
targeting? If marketing is targeting mainly web-savvy groups such as
students, then the primary delivery mechanism for information can, and
probably should, be different from what might be best for a more diverse
or less-savvy audience.

The audience segments that I am most familiar with are, typically, not
comfortable doing web lookups (regardless of the format the info is in
once they find it) and often do not have a reliable, easy to use,
affordable connection to the web. These audience segments include small
businesses, small volunteer organisations such as church groups, and
seniors (btw, there is a fair overlap between these groups). People in
these groups very much need free (in both senses) software, but their
information-gathering methods are very different from, say, students or
people in in larger businesses.

--Jean

In our county, we use OOo (switching to LibO) instead of MS Office
just b/c of the cost of upgrading MS Office. There have been several
occasions where I wanted to copy/paste all the OOo docs and put them
in our intranet site b/c I absolutely hated searching the ODT
documents.

I think if a new menu options was added to the LibO suite--Help >
Online Support--it could probably encourage people to start searching
for documentation online. I threw this together real quick but I think
focusing the documentation for the web could make the online
documentation have a similar look and feel to ODT/PDF documentation.

http://support.thoughtreactor.com/1/

I broke this down by application (Writer, Calc, etc.), then by
chapter, and within each chapter, I've broken it down further by
OOoHeading1. I felt this put enough information on a page to fill it,
but not overwhelm the user with information.

I never thought about people with limited bandwidth--I guess I don't
have to worry about that where I live. :slight_smile: But, like I said earlier, I
think it would be a good idea to export the online documentation to
PDF/ODT and include that in the LibO install so the users don't have
drain their already limited internet.

Also--who creates the included help file within LibO? Is the
information separate from from the ODT docs?

Hi Jeff,

-----
Jeff Prater

>

[...]

I never thought about people with limited bandwidth--I guess I don't
have to worry about that where I live. :slight_smile: But, like I said earlier, I
think it would be a good idea to export the online documentation to
PDF/ODT and include that in the LibO install so the users don't have
drain their already limited internet.

Lucky you. I do care about the bandwidth, because I in fact have a
really crappy internet connection. My connection breaks down quite
often, so I have no internet at all. I have a reasonable connection at
work, but there I can't do LibO work at all. So a method, that allows
me to work on a document offline would be much appreciated. :wink:

Also--who creates the included help file within LibO? Is the
information separate from from the ODT docs?

As far as I know, the help file within LibO/OOo are separate. They are
different from the user guides we produce at OOoAuthors. I have never
helped with translating those files, but I guess Sophie or André (or
someone else) could tell you more about those files. They are part of
the source code.

Sigrid

More info on the PediaPress extension: I've now found that the OOo wiki
is already using it.

As I said above, ODTs and PDFs exported from the wiki are very poor for
complex books like the user guides. For example, in addition to other
layout problems I mentioned, I now recall that if you aggregate multiple
pages into the PDF output, you lose the hierarchy, especially once you
include several chapters.

One can export the Wiki to ODT and clean up the result, but the cleanup
is a lot of work. I had thought that less work was needed for the OOo
Basic Guide, the OOo Admin Guide, and and the Developer's Guide, but I
was wrong. The person who does the work says it varies from manageable
(on a small doc like the Admin Guide) to a very long process for the
large Developer's Guide.

So I repeat what I said earlier: the PediaPress extension to MedaiWiki
may work well with some fairly simple Wiki page sources, but when you
have complex formatting the output starts to look VERY amateurish and
unprofessional. There are ways to work around this, but not quickly and
easily. Going the other way, from ODT to wiki, is also a lot of work but
the results in multiple outputs are much better.

--Jean

In addition to what is already described, OOo/LibO has other major issues in "export to web" function.

1. Links that jump to a heading or a bookmark will not work when the article is saved as mediawiki.
2. We cannot break the article in separate web-pages (ideally separate web-pages for each heading, up to a selectable level)

And as we have already seen, the web->OOo/LibO conversion is not at all possible.

This only shows OOo/LibO is an the offline editor, and any web-compatibility would take a major re-write.

In fact, currently OOo/LibO does not even have an updater which would reduce the downloading tremendously.
We cannot even copy and paste a web page into Writer: The links have to be broken manually.

So overall OOo/LibO is NOT designed for internet at all.
Any compatibility is only an afterthought; and a clumsily tacked on "feature" that does not work fully.

I wonder if all this is part of the LibO roadmap.

-Narayan

Narayan Aras wrote:

OOo/LibO is an the offline editor, and any web-compatibility would
take a major re-write.

There were some steps taken in the direction of an "ODF wiki", which
would probably be the best solution for this use case, see
http://odf-at-www.openoffice.org/ and the screencasts there (those
linked in http://wiki.services.openoffice.org/wiki/ODF@WWW/ODF_Wiki are
still working).

But, as far as I know, no code has been released yet, so this is only a
possible solution for the not-so-near future; I agree that ODF seems the
best format to use for the time being.

Regards,
  Andrea.

Hi, :slight_smile:

I've been reading this thread, and my feelings are somewhat split.

On reflection, as a general idea, I like the idea of having the docs
on a wiki, because of the easy availability and searching of all the
content. In the fairly near future, LibO's built-in help is going to
be wiki-based. If I'm not mistaken about the plans, it will be
available within LibO via an interface that fetches from the Web
initially and then stores locally.

MSO and Windows has this functionality, and it makes updates easy to provide.

Production-side, it could work if the basic formatting of content is
kept simple and complies with some production guidelines.

If we agreed on that, we could be up and working quickly.

I do think we should try to use the material currently available from
OOo as a starting point, and should then start writing on our own. In
the not-so-far future, the UIs of LibO and OOo are going to diverge to
such a point that there won't be sufficient commonality to make it
worthwhile trying to write "one size fits all" docs anyway.

But:

1) The formatting you can do on a wiki is quite rudimentary. And
manual. The writer is faced with the task of being a typesetter at the
same time. And the editor has to tread carefully between all the
mark-up.

The style sheets currently available on the TDF wiki are quite
rudimentary, and would need some
adaptation/enhancement/reconfiguration.

2) I've been summarily investigating the availability of workflow
management extensions for MediaWiki and haven't found what I hoped
for.

Nevertheless, one *could* use the concept of group access to partially
manage roles/permissions, combined with a previously-laid-down set of
agreed procedures. Even so, basically it would be quite a "manual"
process that depends a lot on the discipline and cooperation of the
team contributors.

Speaking personally, I'm not too much into the idea of "throwing the
doors open to the world" to get people writing, because *quality* is
likely to take a steep dive, or to create a big post-editing workload.

One thing we've got with the material that Jean and Ron have been
porting is *truly professional-quality* documentation in terms of the
copy (I'm not thinking about the presentation, which is also up to the
same level). And my ambition for the LibO project is to maintain that
high quality.

3) Michael is very keen on using Drupal as the team's tool. I "have a
date" with him this week to evaluate what he already has available,
and to hear/see - in concrete terms bereft of hype and jargon - what
could be developed. My past experience with CMS products tells me that
Drupal certainly *could potentially* provide the docs team with tools.
But I'm uncertain about who's going to do the development, and about
the current progress and expected readiness deadline of that
development.

We need a working system *quickly*, so that we can stop debating on
the list and actually start producing documentation.

4) Jean has oooauthors.org up and running. I've not taken time out to
see the workflow organization much, but I'm pretty sure she's got
something acceptable that's already operational.

I must say that it rather gets in my face that it's branded OOo and
not LibO, but never mind. I would also prefer it to be a TDF/LibO
resource, too, but it's not. However, it does have the advantage that
*it exists and works*.

Aside from oooauthors, we don't have *any* automated workflow for
working with ODF/ODT files (even though they are in many ways a better
starting point for conversions and excellent presentation).

So, as you can see, the issue of "wiki, ODT or Drupal" is very much a
swings and roundabouts thing.

But I'm starting to drift towards wiki and a Web-based documentation
that we then also export to PDF, and that is easily consultable by our
users *now*. It's the quickest operational solution, barring Jean's
oooauthors.

I'm trying to figure out a workflow that uses the TDF wiki. I've been
working on some Linux installation instructions, and on the TDF
community bylaws, which has taken most of the free time I have to give
the project. But I'll be having some more time in the next few days.

I'm very impatient to get to a point at which I can actually start
*producing documentation*. I'm hoping that we're all going to arrive
at a consensus quickly, and that we're not all going to be pulling in
different directions like a herd of cats.

So much time is wasting, and we have *so little* documentation ready
for our users...

I think we need to choose an acting team lead to direct things. I
asked Jean, but she's not willing.

I'm offering to take on the role myself.

Would I have your support and cooperation for that? Or are there other
candidates?

I'm hoping that as many of you as possible will respond one way or another...

Over to you guys.

David Nelson

In my opinion, we should only have a single version of documentation for
both web, print, and the built-in "help." I was looking at this
project--Sphinx--and it looks like it could meet all of these needs.

http://sphinx.pocoo.org/

And it's open source!

Hi Jeff, :slight_smile:

In my opinion, we should only have a single version of documentation for
both web, print, and the built-in "help." I was looking at this
project--Sphinx--and it looks like it could meet all of these needs.

If you can persuade the devs to adopt Sphinx, it could be a good tool
for documenting the code base, but it's not relevant to the docs
team's needs...

But one single set of documentation for all media might make sense...

David Nelson

Jeff Prater wrote:

In my opinion, we should only have a single version of documentation for
both web, print, and the built-in "help."

I believe the built-in help is specific enough to be a text separate
from the other documentation; for example:
- a manual is a structured text, whereas the built-in help is just a set
of pages
- a manual is supposed to be read consequentially while the built-in
help has no fixed entry point and is mainly accessed by searching
- a manual will possibly be printed and should look nice printed, while
it doesn't make a lot of sense to print the built-in help

Regards,
  Andrea.

Jeff Prater wrote:
> In my opinion, we should only have a single version of documentation for
> both web, print, and the built-in "help."

I agree with what Andrea says.

In addition, the help file is supposed to explain the product screen-by-screen and control-by-control.
The reason is the user would mostly jump from a particular screen, and you have to help him about that screen.

On the other hand, a user's manual would have more theory (compared to built-in help) and also a different flow of topics.
So both these documents have to be separate.

Probably Microsoft has tried to solve this by inserting "All about" sections in its help file.
So while the help screen focuses on the controls of a particular screen, the overall picture is not lost.
The user has TWO choices now: He can check what a control does, or understand the entire topic top-down.