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

classic Classic list List threaded Threaded
24 messages Options
Next » 12
Narayan Aras Narayan Aras
Reply | Threaded
Open this post in threaded view
|

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


Hi all,

I do not know if this is the right forum (and the right time) to put this idea, but why are we circulating odt/pdf files for proofreading?

I have written a 380-page user manual in odt; and also written several help docs in wiki format.
The difference was odt writing was a single-author effort, but wiki was supposed to be collaborative.

Besides, mediawiki has extension that can  export to odt/pdf any time and make it available for offline reading or printing.

See the example here: http://www.den4b.com/wiki/ReNamer
At the time of starting the wiki, I already had written most of the manual in odt format.
So I saved the individual chapters in mediawiki format, and pasted them in the wiki pages.
I had to upload all figures separately and link them. But on the whole the experience was smooth.

Wiki also eliminates the proofreading effort, as the others can directly edit the original effort.

Just my two cents.

Regards,
Narayan
     
--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***

Jean Weber Jean Weber
Reply | Threaded
Open this post in threaded view
|

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

On Fri, 2010-12-03 at 20:53 +0530, Narayan Aras wrote:

> Hi all,
>
> I do not know if this is the right forum (and the right time) to put this idea, but why are we circulating odt/pdf files for proofreading?
>
> I have written a 380-page user manual in odt; and also written several help docs in wiki format.
> The difference was odt writing was a single-author effort, but wiki was supposed to be collaborative.
>
> Besides, mediawiki has extension that can  export to odt/pdf any time and make it available for offline reading or printing.
>
> See the example here: http://www.den4b.com/wiki/ReNamer
> At the time of starting the wiki, I already had written most of the manual in odt format.
> So I saved the individual chapters in mediawiki format, and pasted them in the wiki pages.
> I had to upload all figures separately and link them. But on the whole the experience was smooth.
>
> Wiki also eliminates the proofreading effort, as the others can directly edit the original effort.
>
> Just my two cents.

This was discussed here earlier. For OOo/LibO user guides (docs aimed at
end users, not developers), ODT as a source doc works better (at least
in the short term) for these reasons:

1) LibO docs team is using the OOo docs as a starting point, and the OOo
docs are in ODT. (The user docs on the OOo wiki are not up to date.)

2) Going from ODT to wiki gives a good layout, but going from wiki to
ODT (or PDF) does not; the layout sucks. User guides have too many
illustrations, tables, and other features; Mmch fixing up is necessary
after export from wiki to ODT if you want a professional looking result.

3) Going from ODT to PDF is easy, and layout is preserved. As stated in
(2), going from wiki to PDF gives poor layout that needs much work.

4) Using a wiki does NOT eliminate the proofreading effort. In my
experience, using a wiki as the source document results in MORE need for
proofreading. Althugh reviewing/editing may be done on the wiki,
tracking the changes is not as easy as in ODT; asking questions and
getting answers is not as easy; edited wiki pages often/usually need
further editing for grammar, comprehension, etc; and much more checking
of page layout etc is needed after export to ODT.

5) At OOo most of the people interested in working on user guides say
they prefer to work in the ODT files. It may turn out to be different at
LibO.

--Jean


--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***
Wheatbix Wheatbix
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by Narayan Aras
On Sat, Dec 4, 2010 at 12:53 AM, Narayan Aras <[hidden email]> wrote:

>
> Hi all,
>
> I do not know if this is the right forum (and the right time) to put this idea, but why are we circulating odt/pdf files for proofreading?
>
> I have written a 380-page user manual in odt; and also written several help docs in wiki format.
> The difference was odt writing was a single-author effort, but wiki was supposed to be collaborative.
>
> Besides, mediawiki has extension that can  export to odt/pdf any time and make it available for offline reading or printing.
>
> See the example here: http://www.den4b.com/wiki/ReNamer
> At the time of starting the wiki, I already had written most of the manual in odt format.
> So I saved the individual chapters in mediawiki format, and pasted them in the wiki pages.
> I had to upload all figures separately and link them. But on the whole the experience was smooth.
>
> Wiki also eliminates the proofreading effort, as the others can directly edit the original effort.
>
> Just my two cents.
>
> Regards,
> Narayan

Narayan,
This exact topic was discussed at the documentation conference call.
As Jean has expressed we will most likely be continuing with the
development in ODT format mainly due to page formatting and publishing
reasons. There will be an 'Online Help' which is being developed for
inclusion directly into LibreOffice.

As a part of the documentation system on the longer term LibreOffice
Drupal website, which will replace the current test.libreoffice.org
site in a couple of months, we are building tools which will allow
authors to source parts of a document from other authors but still
maintain the quality control that a wiki lacks.

Michael Wheatland

--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***
vpanter vpanter
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by Narayan Aras
Hello Narayan,


Op 3/12/2010 16:23, Narayan Aras schreef:

> Hi all,
>
> I do not know if this is the right forum (and the right time) to put this idea, but why are we circulating odt/pdf files for proofreading?
>
> I have written a 380-page user manual in odt; and also written several help docs in wiki format.
> The difference was odt writing was a single-author effort, but wiki was supposed to be collaborative.
>
> Besides, mediawiki has extension that can  export to odt/pdf any time and make it available for offline reading or printing.
>
> See the example here: http://www.den4b.com/wiki/ReNamer
> At the time of starting the wiki, I already had written most of the manual in odt format.
> So I saved the individual chapters in mediawiki format, and pasted them in the wiki pages.
> I had to upload all figures separately and link them. But on the whole the experience was smooth.
>
> Wiki also eliminates the proofreading effort, as the others can directly edit the original effort.
>
> Just my two cents.
>
> Regards,
> Narayan
>    
Isn't it a good idea to use LibO to describe how to use it? ;-)
I have been translating OOo guides and learned a lot about the software
by using it.

Best regards

--
Leo Moons
LibreOffice

Nous sommes condamnés à être libres


--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***

Jeff Prater Jeff Prater
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by Narayan Aras
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

On Fri, Dec 3, 2010 at 10:23 AM, Narayan Aras <[hidden email]>wrote:

>
> Hi all,
>
> I do not know if this is the right forum (and the right time) to put this
> idea, but why are we circulating odt/pdf files for proofreading?
>
> I have written a 380-page user manual in odt; and also written several help
> docs in wiki format.
> The difference was odt writing was a single-author effort, but wiki was
> supposed to be collaborative.
>
> Besides, mediawiki has extension that can  export to odt/pdf any time and
> make it available for offline reading or printing.
>
> See the example here: http://www.den4b.com/wiki/ReNamer
> At the time of starting the wiki, I already had written most of the manual
> in odt format.
> So I saved the individual chapters in mediawiki format, and pasted them in
> the wiki pages.
> I had to upload all figures separately and link them. But on the whole the
> experience was smooth.
>
> Wiki also eliminates the proofreading effort, as the others can directly
> edit the original effort.
>
> Just my two cents.
>
> Regards,
> Narayan
>

--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***

Jean Weber Jean Weber
Reply | Threaded
Open this post in threaded view
|

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

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

On Fri, 2010-12-03 at 20:07 -0500, Jeff Prater wrote:

> 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
>
> On Fri, Dec 3, 2010 at 10:23 AM, Narayan Aras <[hidden email]>wrote:
>
> >
> > Hi all,
> >
> > I do not know if this is the right forum (and the right time) to put this
> > idea, but why are we circulating odt/pdf files for proofreading?
> >
> > I have written a 380-page user manual in odt; and also written several help
> > docs in wiki format.
> > The difference was odt writing was a single-author effort, but wiki was
> > supposed to be collaborative.
> >
> > Besides, mediawiki has extension that can  export to odt/pdf any time and
> > make it available for offline reading or printing.
> >
> > See the example here: http://www.den4b.com/wiki/ReNamer
> > At the time of starting the wiki, I already had written most of the manual
> > in odt format.
> > So I saved the individual chapters in mediawiki format, and pasted them in
> > the wiki pages.
> > I had to upload all figures separately and link them. But on the whole the
> > experience was smooth.
> >
> > Wiki also eliminates the proofreading effort, as the others can directly
> > edit the original effort.
> >
> > Just my two cents.
> >
> > Regards,
> > Narayan
> >
>




--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***
Narayan Aras Narayan Aras
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by vpanter

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

Actually I agree there! :)

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

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
     
--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***

Jean Weber Jean Weber
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by Jeff Prater
On Fri, 2010-12-03 at 20:07 -0500, Jeff Prater wrote:
> ... I agree with
> Narayan on how initial documentation should be developed...
>
> 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...

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


--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***
Narayan Aras Narayan Aras
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by Jean Weber

> This was discussed here earlier. For OOo/LibO user guides (docs aimed at
> end users, not developers), ODT as a source doc works better (at least
> in the short term) for these reasons:
>
> 1) LibO docs team is using the OOo docs as a starting point, and the OOo
> docs are in ODT. (The user docs on the OOo wiki are not up to date.)

> 2) Going from ODT to wiki gives a good layout, but going from wiki to
> ODT (or PDF) does not; the layout sucks. User guides have too many
> illustrations, tables, and other features; Mmch fixing up is necessary
> after export from wiki to ODT if you want a professional looking result.

> 3) Going from ODT to PDF is easy, and layout is preserved. As stated in
> (2), going from wiki to PDF gives poor layout that needs much work.
>
> 4) Using a wiki does NOT eliminate the proofreading effort. In my
> experience, using a wiki as the source document results in MORE need for
> proofreading. Althugh reviewing/editing may be done on the wiki,
> tracking the changes is not as easy as in ODT; asking questions and
> getting answers is not as easy; edited wiki pages often/usually need
> further editing for grammar, comprehension, etc; and much more checking
> of page layout etc is needed after export to ODT.
>
> 5) At OOo most of the people interested in working on user guides say
> they prefer to work in the ODT files. It may turn out to be different at
> LibO.
>
> --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.


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! :)

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

The mother of all wikis, Wikipedia, has other more sophisticated tools for managing wikis.
These are available for free download.

In fact, I have found that wiki's "Discussion" page is the idea place to ask question, or even to place an alternative mock up of the page. Then other reviewers can compare these alternatives and post their opinion on these versions. Finally we may use one of the versions or a mix of them.

I have actually DONE this in the example provided. :)

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.

Regards,
Narayan



     
--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***

Narayan Aras Narayan Aras
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by Jean Weber

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

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

Does it not strike you as a valid development target for LiBo?
LiBo should excel in this area; because wiki (and web in general) will touch many more lives in future!

What is a software if it cannot resolve the pain points of its own help authors?

Please pass on the word to Charles Schulz! :)

-Narayan
     
--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***

Jean Weber Jean Weber
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by Narayan Aras
Comments interleaved below. --Jean

On Sat, 2010-12-04 at 08:40 +0530, Narayan Aras wrote:

> *************************
> 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! :)
>
> @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


--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***
Jeff Prater Jeff Prater
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by Jean Weber
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?


On Fri, Dec 3, 2010 at 10:03 PM, Jean Hollis Weber <[hidden email]>wrote:

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

--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***

Jean Weber Jean Weber
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by Narayan Aras
On Sat, 2010-12-04 at 09:17 +0530, Narayan Aras wrote:

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

> LiBo should excel in this area; because wiki (and web in general) will touch many more lives in future!
>
> What is a software if it cannot resolve the pain points of its own help authors?
>
> Please pass on the word to Charles Schulz! :)
>
> -Narayan
>      




--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***
Jean Weber Jean Weber
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by Jeff Prater
Jeff, thanks for that clarification. Some comments interleaved below.
--Jean

On Fri, 2010-12-03 at 23:10 -0500, Jeff Prater wrote:
> 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

>
>
> On Fri, Dec 3, 2010 at 10:03 PM, Jean Hollis Weber <[hidden email]>wrote:
> >
> >
> > 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
>




--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***
Jeff Prater-2 Jeff Prater-2
Reply | Threaded
Open this post in threaded view
|

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

-----
Jeff Prater


On Fri, Dec 3, 2010 at 11:30 PM, Jean Hollis Weber <[hidden email]> 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. :) 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?

--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***

eskroni eskroni
Reply | Threaded
Open this post in threaded view
|

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

Hi Jeff,

Am Sat, 4 Dec 2010 11:49:40 -0500
schrieb Jeff Prater <[hidden email]>:

> -----
> Jeff Prater
>
>
> On Fri, Dec 3, 2010 at 11:30 PM, Jean Hollis Weber
> <[hidden email]> wrote:
> >
[...]

> I never thought about people with limited bandwidth--I guess I don't
> have to worry about that where I live. :) 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. ;)

> 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

--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***
Jean Weber Jean Weber
Reply | Threaded
Open this post in threaded view
|

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

In reply to this post by Jean Weber
On Sat, 2010-12-04 at 13:59 +1000, Jean Hollis Weber wrote:

> On Sat, 2010-12-04 at 08:40 +0530, Narayan Aras wrote:
> >
> > prediapress is running a successful "Print-on-Demand" business out of printing books from wikis.
> > ...
> >
> > Each book is nothing but an exported pdf from wiki....
> >
> > 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.)

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


--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***
Narayan Aras Narayan Aras
Reply | Threaded
Open this post in threaded view
|

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


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
     
--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***

Andrea Pescetti Andrea Pescetti
Reply | Threaded
Open this post in threaded view
|

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

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.


--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***

davidnelson davidnelson
Reply | Threaded
Open this post in threaded view
|

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

Hi, :-)

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

--
Unsubscribe instructions: E-mail to [hidden email]
List archive: http://www.libreoffice.org/lists/documentation/
*** All posts to this list are publicly archived for eternity ***

Next » 12