Documentation/Production

    From The Document Foundation Wiki
    Gnome-document-open-recent.svg

    This page was marked as inactive and is retained for historical reference.
    For up to date information, please refer to the Documentation Development page.

    Discussion List for Documentation

    documentation@global.libreoffice.org: Group for people working on LibreOffice documentation and help system

    Subscription: documentation+subscribe@global.libreoffice.org

    Digest subscription: documentation+subscribe-digest@global.libreoffice.org

    Archives (old): https://www.libreoffice.org/lists/documentation/
    Archives (new): http://listarchives.libreoffice.org/global/documentation/

    Mail-Archive.com (old): https://www.mail-archive.com/documentation@libreoffice.org/
    Mail-Archive.com (new): https://www.mail-archive.com/documentation@global.libreoffice.org/

    Task List for User Guides

    Update user guides

    The chapters in the user guides need to be updated for LibreOffice 3.4.

    See the Documentation Development page for the status of chapters and what needs to be done.

    Proposals for user guide revision

    Proposal for Major Revision of Getting Started Guide

    Proposal for Major Revision of Writer Guide

    Wish List for User Documentation

    Please list here the things you would like to see provided as user documentation. Obviously we can't do everything unless we have enough people to do the work, but it's good to have a "wish list" -- someone might see one of the items and say "I can do that!"

    • User guides in wiki format
    • FAQs (on this wiki)
    • HowTos
    • Re-organise the Documentation wiki-pages structure
    • De-geek the wiki page on Bug-reporting
    • De-geek the HowTo use Alfresco that is in Alfresco and possibly add it to these wiki-pages. (After David has updated that guide in the Resources section in Alfresco).
    • Tutorials, in PDF & ODT
    • Tutorials, video
    • Training materials (may be done through another group in LibreOffice community?)
    • Documents aimed at specific audiences, e.g. technical writers, small business, university students
    • Short books on specific topics aimed at intermediate and advanced users
    • www.tutorialsforopenoffice.org/index.html Will be adding support for LibreOffice in the near future.
    • A library of material to be used in more than one doc. For example, some info on setup, customisation, printing, and PDF export is used in guides for several components. (For use by Docs team, not for public.)
    • A collection of examples for LibreOffice Math (e.g. markup language for a 4x4-matrix with placeholders, spread over multiple lines)
    • Update and adapt the OpenOffice.org 2.0 migration guide for LibreOffice

    Offer from Friends of OpenDocument re printed copies

    Note: This offer was accepted and printed copies of the user guides are being produced and sold through Lulu.com.

    Friends of OpenDocument, Inc (FoOD for short), an Australia-based not-for-profit association, has offered to produce printed copies of the user guides for LibreOffice.

    • Sales are currently through Lulu and books can be made available through Amazon and other online retailers through the FoOD account at Lightning Source (an on-demand printer owned by Ingram, the largest distributor of books through online and offline bookstores).
    • There is no cost for making books available for sale on the Lulu website. However, there are costs for making books availalbe through Lightning Source to Amazon etc.
    • Books are given Australian ISBN through the FoOD account.
    • FoOD takes 50cents per book sold to cover admin costs, mostly for accounting/auditing and filing of paperwork required by the government. FoOD does not need to pay taxes on sales, either in the USA or in Australia.
    • We provide full accounting: summaries on the FoOD website, details available on request.
    • All profits from sales of LibO books would be forwarded to the TDF account. We can work out details of how often to do this.
    • FoOD would like someone from the LibO documentation team to take responsibility for providing cover art and interior PDFs suitable for use with Lulu. Full information and training will be provided.

    TDF is, of course, welcome to set up its own account at Lulu or Lightning Source or elsewhere, instead of using FoOD's services.

    Wish List for Developer Documentation

    Please list here the things you would like to see provided as developer documentation.

    • Packaging (.deb, .rpm, .dmg, .pisi,...)
    • UNO/LibreOffice Object Model (objects, methods, properties) would help macro and LibreOffice developers alike.

      A few diagrams of the object model hierarchy would help newcomers get started faster.  

    • Developer level workflow including git, running soffice with the debugger and when to build all/modules.  Developer FAQs for different phases of development.  (These probably belong in Development section).


    Workflow

    (Added by Jean Hollis Weber)

    Here is what I want to see. I don't care what s/w is used, as long as I can track development easily and without ambiguity.

    Preamble

    Best source doc filetype is ODT because it is the easiest to use for high-quality output to a variety of other formats (PDF, wiki, ePub, HTML, whatever).

    Must be able to track dates, file versions, & status. Separate folders work and are easy for everyone to see what's at which stage of development. Changing the filename at each stage to show date and initials also makes it easy to everyone to see what's going on. That's a bit low-tech, but it works... including when the files have been downloaded to someone's computer. No accidental overwriting, easy to tell which file is what.

    Someone must be able to over-ride "checkout" if the person who checks out a file doesn't return it in a reasonable time and doesn't respond to requests for status updates or unlocking of the file. This happens all the time but should not be allowed to stall work on a book.

    Workflow

    1) Create draft doc, upload to Drafts folder, mark as ready for review.
    2) Reviewer checks out draft doc, makes changes with tracking on, uploads result to Feedback.
    3) Author (or someone else, depending on book & circumstances) revises draft, removes change tracking up to that point, replaces file in Drafts & marks as ready for review.
    4) Repeat 2 & 3 as needed.
    5) When ready, author (or other) puts file into Copyediting/Proofing & marks as ready for editing.
    6) Copyeditor does job with change tracking on, puts into Feedback.
    7) Author (or other) accepts/rejects edits, puts file into Indexing/Final Layout folder, marks as ready for further work.
    8) Indexer/Book Coordinator/whoever final checks all and puts file into Published folder (or returns to Feedback for further work).
    9) Book Coordinator/Publisher/whoever outputs file into various formats (PDF, others to be decided) and makes available to public, with a copy
    into the working folder for next revision.

    People Needed

    In addition to volunteer writers, reviewers, editors, indexers, researchers etc., we need some people to help coordinate and mentor volunteers.

    Documentation Coordinators

    People are needed to take responsibility for specific documentation projects. This doesn't mean you have to do all the work! But you do need to commit time to coordinating volunteers doing smaller pieces of the work, keep track of what need to be done, who is doing what, what's on time or behind schedule or not getting done at all (for example, when updating a book to the latest version of the software). Jean Weber has been doing most of this at OOoAuthors, but she can't keep up with everything.

    Mentors

    People are also needed to help others get started and also help them with general technical writing issues. We get a lot of volunteers who want to improve their technical writing skills, but we don't have enough mentors to help them.

    Conference Call

    The date/time of the first documentation conference call is Saturday, 27 November 2010, 11 pm CET. You can do time conversions here: http://doodle.com/qq8hiysi36fhkwy4

    Conference call wiki page for more info and the agenda (feel free to add stuff, but there's quite a list already):
    Documentation/ConfCalls


    Sample screenshots

    (Added by Jean Hollis Weber, 9 November 2011.)

    After upgrading to Ubuntu 11.10, I have been unable to get the "XP Silver" theme installed, possibly because this version of Ubuntu uses Gnome 3, not Gnome 2.

    I have found what I consider an acceptable replacement theme, a combination of an GTK+ theme called "Adwaita" (shipped with Ubuntu 11.10) and a Window theme called Evolve, which must be downloaded and installed (instructions below). Note that using the Evolve GTK+ theme does not give the desired result (the contrast is not good enough).

    Below is an example screenshot.

    Sample of Adwaita + Evolve theme

    To install the Evolve theme, follow the instructions on this page: http://browse.deviantart.com/customization/skins/linuxutil/desktopenv/gnome/gtk3/#/d4dn66o.

    Ubuntu 11.10 users can install it using the commands below,

    sudo add-apt-repository ppa:webupd8team/themes
    sudo apt-get update
    sudo apt-get install evolve-gtk-theme
    

    Now install the Gnome Tweak Tool:

    sudo apt-get install gnome-tweak-tool
    

    This creates an app called "Advanced Settings". Open that and (a) if necessary, select Adwaita as the GTK+ theme; and (b) change the Windows theme to Evolve.


    IN ADDITION to setting up the theme described above, you need to select the Galaxy icon set in LibreOffice. (This is not a Ubuntu icon set. This is a LibreOffice icon set.)

    The choice of the LO icon set is found in Tools > Options >LibreOffice > View; in the User Interface section of that page, under Icon size and style, choose Galaxy (default).


    (Older notes, added by Jean Hollis Weber, 17 June 2011.)

    NOTE: The user guides in English are using the "XP Silver" theme. Other language groups may use Clearlooks or some other them.

    Below are two sets of screenshots, for comparison. Both were taken from the same document on Ubuntu 11.04. One set (with the blue title bars) uses the Clearlooks theme; the other (all gray) uses the XP-Silver theme developed by Michele Zarri for the OpenOffice.org user guides.

    Important criteria for screenshots in the user guides include high contrast between the text and background in all parts of the screenshot, and high quality printing in black and white (mainly for printed copies available through Lulu, but also for anyone printing from the PDFs). I have recommended using the XP-Silver theme for the user guides, but this is open for discussion.

    You can download the XP-Silver theme here. It is a zip file containing instructions and two other files.

    Sample 1: Clearlooks theme
    Sample 1: XP Silver theme
    Sample 2: Clearlooks theme
    Sample 2: XP Silver theme