RE: [libreoffice-documentation] How about creating manuals in mediawiki (and then export to odt and pdf when required)?
> 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. *** BTW all this discussion means LibO should make it a priority development target to be compatible with such web-based documentation. Regarding the "online vs offline" debate, I have seen the following arguments: Why online: 1. The time of offline editors like MSO and OOo has come and gone (in favor of online editors like Google Docs and MSO live) 2. The netbooks and pads will force people towards online editors. Why offline: 1. Most/many countries and regions don't have enough bandwidth, or reliable connection, 2. Many users have or their lifestyle forces them to have only intermittent access to net. 2. Even if the net is accessible, many people can't afford the cost. So catering to both types of users would mean making a documentation system that is convertible. This conversion may not be "live": For example, wikipedia does the wiki-to-pdf conversion periodically. On the other hand, there is the PediaPress approach (convert your own odt/pdf ; or Print-on-demand). Regards, Narayan -- Unsubscribe instructions: E-mail to documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to this list are publicly archived for eternity ***
Re: [libreoffice-documentation] How about creating manuals in mediawiki (and then export to odt and pdf when required)?
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. -- Unsubscribe instructions: E-mail to documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to this list are publicly archived for eternity ***
Re: [libreoffice-documentation] How about creating manuals in mediawiki (and then export to odt and pdf when required)?
Hi Jeff, :-) On Mon, Dec 6, 2010 at 01:04, 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 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 -- Unsubscribe instructions: E-mail to documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to this list are publicly archived for eternity ***
Re: [libreoffice-documentation] How about creating manuals in mediawiki (and then export to odt and pdf when required)?
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! -- Unsubscribe instructions: E-mail to documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to this list are publicly archived for eternity ***
Re: [libreoffice-documentation] 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 documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to t
RE: [libreoffice-documentation] 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/o...@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 documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to this list are publicly archived for eternity ***
RE: [libreoffice-documentation] 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 documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to this list are publicly archived for eternity ***
RE: [libreoffice-documentation] How about creating manuals in mediawiki (and then export to odt and pdf when required)?
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 documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to this list are publicly archived for eternity ***
Re: [libreoffice-documentation] 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 : > - > Jeff Prater > > > On Fri, Dec 3, 2010 at 11:30 PM, Jean Hollis Weber > 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 documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to this list are publicly archived for eternity ***
Re: [libreoffice-documentation] 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 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 documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to this list are publicly archived for eternity ***
Re: [libreoffice-documentation] How about creating manuals in mediawiki (and then export to odt and pdf when required)?
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 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 documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to this list are publicly archived for eternity ***
RE: [libreoffice-documentation] How about creating manuals in mediawiki (and then export to odt and pdf when required)?
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 documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to this list are publicly archived for eternity ***
Re: [libreoffice-documentation] How about creating manuals in mediawiki (and then export to odt and pdf when required)?
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 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 documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to this list are publicly archived for eternity ***
RE: [libreoffice-documentation] How about creating manuals in mediawiki (and then export to odt and pdf when required)?
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 documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to this list are publicly archived for eternity ***
RE: [libreoffice-documentation] How about creating manuals in mediawiki (and then export to odt and pdf when required)?
> 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 documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to this list are publicly archived for eternity ***
RE: [libreoffice-documentation] How about creating manuals in mediawiki (and then export to odt and pdf when required)?
> 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 documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to this list are publicly archived for eternity ***
Re: [libreoffice-documentation] How about creating manuals in mediawiki (and then export to odt and pdf when required)?
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 documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to this list are publicly archived for eternity ***
RE: [libreoffice-documentation] How about creating manuals in mediawiki (and then export to odt and pdf when required)?
> 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 documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to this list are publicly archived for eternity ***
Re: [libreoffice-documentation] 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 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 documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to this list are publicly archived for eternity ***
Re: [libreoffice-documentation] 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 On Fri, Dec 3, 2010 at 10:23 AM, 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. > > Regards, > Narayan > -- Unsubscribe instructions: E-mail to documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to this list are publicly archived for eternity ***
Re: [libreoffice-documentation] How about creating manuals in mediawiki (and then export to odt and pdf when required)?
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 documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to this list are publicly archived for eternity ***
Re: [libreoffice-documentation] How about creating manuals in mediawiki (and then export to odt and pdf when required)?
On Sat, Dec 4, 2010 at 12:53 AM, 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. > > 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 documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to this list are publicly archived for eternity ***
Re: [libreoffice-documentation] 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 documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to this list are publicly archived for eternity ***
[libreoffice-documentation] 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 documentation+h...@libreoffice.org List archive: http://www.libreoffice.org/lists/documentation/ *** All posts to this list are publicly archived for eternity ***
