Documentation/Development

From The Document Foundation Wiki
Jump to: navigation, search

Documentation Development

The official user guides are on our Publications page.

We use the ODFAuthors website as a production site, with published documentation placed on Publications page. The official LibreOffice website then links to those guides.

If you would like to join the team, please:

  1. Sign up for the mailing list. Send a blank e-mail message to documentation+subscribe@global.libreoffice.org. You should receive a response containing further instructions.
  2. Email the mailing-list to introduce yourself briefly (we don't need a CV!). Documentation Team mailing list
  3. In your email please request a user account for our ODFAuthors site.

We look forward to hearing from you. :)


First steps with the Documentation team

Contributors Guide

For people joining the Documentation Team. Some chapters are out of date and are being revised.



Separate chapters:       2016-17 version
  1   Joining the LibreOffice Documentation Team   ODT or  PDF   7 Oct 2016
  2 Producing LibreOffice User Guides ODT or PDF 7 Oct 2016
  3 Using the ODFAuthors website ODT or PDF 8 Oct 2016
  4 Style Guide for LibreOffice User Guides ODT or PDF Being revised
  5 Using the LibreOffice Chapter Template ODT Being revised
 

Templates for user guides



        3.3     3.4     3.5-4.3     4.4     5.0  

Source files for cover art (SVG)



                  3.4     3.5  
    3.5 French    
    4.0 front   
    4.0 back   
    4.2-4.3 front   
    4.2-4.3 back   
    5.0 front & back   
   zipped   

What we do

User Guides

Workflow

Workflow on ODFAuthors

Below is the workflow we are theoretically using. In fact, several of the steps in the review process are not occurring, due to lack of people to do them.

Using ODFAuthors website

  1. Create draft document according to:
  2. Upload draft to the appropriate draft folder:
    1. Sign into the ODFAuthors web site.
    2. LibreOffice > English > (appropriate folder for your document) > Drafts. This takes you to the folder your file should be uploaded to.
    3. Click "Add new" and then click File from its menu.
    4. Enter the title and a description of the document.
    5. Click the Browse button to tell the website where the file is located on your hard drive.
    6. Click the Save button to upload the file.
  3. Submit your document for review.
    • Click "State: Internal draft" and select "Submit for publication". (It changes to "State: Pending review".)
  4. Report what you have done to the document team mailing list (documentation@global.libreoffice.org)

Downloading a file for review

  1. Sign into ODFAuthors.
  2. LibreOffice > English > (appropriate folder for your document) > Drafts (or Feedback).
  3. Click the file you want to download. Your browser opens a dialog to download the file.
  4. Change the file's status:
    • Click "State: Pending review" and select Retract. (It changes to "State: Internal draft".)

Uploading a file after a review

  1. Sign into ODFAuthors.
  2. LibreOffice > English > (appropriate folder for your document) > Feedback.
  3. Click "Add new" and then click File from its menu.
  4. Enter the title and a description of the document.
  5. Click the Browse button to tell the website where the file is located on your hard drive.
    • Click the Save button to upload the file.

Submitting your document for review

  1. Navigate to the Draft folder containing the file you downloaded to review.
  2. Change the status of the reviewed document.
  3. Click "State: Internal draft" and select "Submit for publication". (It changes to "State: Pending review".)
  4. Report what you have done to the document team mailing list (documentation@global.libreoffice.org) Generally, the author will review the changes you made accepting or rejecting them individually.
  5. Reviewer checks out draft doc, makes changes with tracking on, checks doc in, promotes to Reviewed space.
  6. Author (or someone else, depending on book & circumstances) revises draft, removes change tracking up to that point, demotes file to Drafts space -- OR skip to Step 5.
  7. Repeat Steps 2 and 3 as needed.
  8. When ready, author (or other) promotes file from Reviewed space to Copyediting/Proofing space.
  9. Copyeditor does job with change tracking on, puts into Feedback.
  10. Author (or other) accepts/rejects edits, puts file into Indexing/Final Layout folder, marks as ready for further work.
  11. Indexer/Book Coordinator/whoever final checks all and puts file into Published folder (or returns to Feedback for further work).
  12. 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.

If you have any questions, remember Documentation Team mailing list and #documentfoundation connect via webchat.

For more information on how to review and update LibreOffice user guides (including image creation, cross-referencing, indexing, and publishing), please see Producing LibreOffice User Guides.

Status of tasks for user guides

This section has been moved to a separate wiki page, User Guide Tasks, where we track progress on the development of each book. It lists who is working on each chapter, the stage of development, and dates.

This page lists known topics that need to be added to the various books to bring them up to date for v5.1. Feel free to add notes on that page.

Using OmegaT for translation

OmegaT is a Computer Aided Translation tool that can be used to handle the translation of the guides produced by the Documentation team. Miloš Šrámek has made a presentation about his workflow, this wiki page describes the process based on the development he shared.

Other Documents

Below are a few of the other documents to be developed.

Administrators' Guide

Could be based on the OpenOffice.org Admin Guide.

Basic Programmers' Guide

Could be based on the OpenOffice.org BASIC Programmers' Guide.

Developers' Guide

Could be based on the OpenOffice.org Developers' Guide.

Math Examples

Here is a first draft - comments welcome.

Wish Lists for Documentation

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

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.  
  • Documentation on using Javascript for Extensions and Macros
  • Documentation on debugging macros/Extensions in Java, Python, Javascript. There is some info on the "how to debug" page existing (scroll to the end), but is is sparse and lacks images/examples to clarify.
  • 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).