Chapter 3 Using the LibreOffice Documentation Team Website

From The Document Foundation Wiki
Jump to: navigation, search
This page contains changes which are not marked for translation.


LibreOffice Initial-Artwork-Logo ColorLogoBasic 500px.png
Documentation Contributors’ Guide

Chapter 3 Using the LibreOffice Documentation Team Website

Introduction

The LibreOffice Documentation team uses The Document Foundation's NextCloud website (https://nextcloud.documentfoundation.org/) for storing, organizing, and tracking working copies of user guide files. It is quite easy to use once you become familiar with it.

Final published versions of the files are stored on the https://documentation.libreoffice.org website in addition to The Document Foundation’s wiki (http://wiki.documentfoundation.org/Documentation/Publications). The Documentation page of the LibreOffice website (https://documentation.libreoffice.org) links to the documents stored on the wiki.

Workflow for producing user guide chapters

Workflow for producing user guide chapters

Workflow description

Refer to the Workflow for producing user guide chapters diagram above and the Organizing workflow through folders diagram below. See also the Tracking progress using the wiki section below for details of the file naming convention used for tracking the progress of a file.

  1. Writer creates a new document, uploads it into the Draft folder under the relevant book, and submits it for review (see Creating a new user guide chapter and Submitting a chapter for review sections below.
  2. Reviewer downloads draft document, makes changes with change tracking on, changes the file name, and uploads the result into the Feedback folder under the relevant book (see Reviewing a chapter section below).
  3. Writer (or someone else, depending on book and circumstances) revises draft, removes change tracking up to that point, uploads file to Draft folder.
  4. Repeat steps 2 and 3 if needed or, if sufficient reviewing has been completed, skip to step 5.
  5. Writer (or other) makes final changes, removes all change tracking, uploads file to Draft folder, submits it for review, and pings the Editor on the Documentation list.
  6. Editor does job with change tracking on, puts result into Feedback.
  7. Writer (or other) accepts/rejects edits, makes any other changes needed, optionally submits for another review or edit, or uploads revised file to Feedback and pings Publisher.
  8. Publisher final checks file and uploads it into Published folder (or returns it to Feedback for further work), publishes it (see Publishing a chapter section below).
  9. Publisher exports file to PDF and makes both ODT and PDF files available to the public, with a copy of the ODT in the working folder for next revision. ( Chapter 2, Producing LibreOffice User Guides for more about the publishing process.)

Organizing workflow through folders

The English section of LibreOffice Documentation folder in Nextcloud has this structure:

    English

        [book name (Calc Guide, for example)]

            [version (6.2, for example)]
            
                Archive

                Draft

                Feedback

                Published

                Source files (pre draft)

                Guide Status.ods

Creating a new user guide chapter

New chapters may be created in two circumstances. The details of how to create a new chapter vary between them and will be discussed separately.

  • Completely new chapter
  • New chapter based on existing chapter (for example, when updating information for a new book about a new version of LibreOffice)

Creating a completely new chapter

Location of latest template file in Nextcloud
  1. Create draft document according to the template (currently LibreOffice_6.x_Template.ott), which you can get from LibreOffice Documentation > English > Contributor Resources in your NextCloud session. Read the following pages:
  2. Save the file using the file naming convention decribed in Chapter 2, Producing LibreOffice User Guides.
  3. Upload draft to the appropriate folder:
    1. Sign into The Document Foundation's NextCloud server (https://auth.documentfoundation.org/saml/).
    2. Go to LibreOffice Documentation > English > [appropriate folder for your document, for example "Calc Guide"] > [appropriate version number for your document, for example "6.2"] > Feedback.
    3. Click on the + icon in the top of the screen
      • Select Upload File.
      • Find and select the file on your computer, then click Open to upload the file to the NextCloud server.
  4. Submit the document for review; see Submitting a chapter for review section below.
  5. Report what you have done, and the location of the file, to the Documentation Team’s mailing list (documentation@global.libreoffice.org).

Creating a new chapter based on an existing chapter

Use this procedure when updating a chapter for a new book about a new version of LibreOffice.

  1. Get a copy of the ODT file for the published chapter for the previous version of LibreOffice.
  2. Rename the copy according to our file naming convention (see Chapter 2, Producing LibreOffice User Guides).
  3. Revise the chapter as needed, normally with change tracking on (see Chapter 2, Producing LibreOffice User Guides). This may include updating the document to utilise the latest User Guide Chapter template. If the changes to the chapter are extensive and reviewing just the changes is considered impractical, then it is acceptable to leave change tracking off.
  4. Upload the result to the Feedback folder for the new book on The Documentation Foundation's NextCloud server.
  5. Submit the document for review; see Submitting a chapter for review section below.
  6. Report what you have done, and the location of the file, to the Documentation Team’s mailing list (documentation@global.libreoffice.org).

Revising an existing user guide chapter

If corrections are required to a previously-published chapter, use this procedure.

  1. Get a copy of the published chapter. DO NOT change the status of the published chapter.
  2. Rename the copy according to our file naming convention (see Chapter 2, Producing LibreOffice User Guides).
  3. Revise the chapter as needed, with change tracking on (see Chapter 2).
  4. Upload the result to the Feedback folder for the existing book.
  5. Submit the document for review (see “Submitting a chapter for review” below).
  6. Report what you have done to the documentation team’s mailing list (documentation@global.libreoffice.org).

Submitting a chapter for review

After you have uploaded a chapter that is ready for review, change the status of the document.

  1. Be sure you are signed into the TDF NextCloud server..
  2. Go to the page for the chapter file.
  3. On the menu bar above the file name, click State: Internal draft and select Submit for publication. (It changes to State: Pending review.)
  4. Report what you have done, and the location of the file, to the documentation team’s mailing list (documentation@global.libreoffice.org).
File:Image2.png

Reviewing a chapter

Refer to Chapter 2, Producing LibreOffice User Guides, for information on what to look for when reviewing a chapter. This section describes how to use the TDF NextCloud website when downloading a chapter for review and uploading a chapter after review.

Downloading a chapter for review

  1. Be sure you are signed into the NextCloud server.
  2. Go to the required folder: LibreOffice > English > [book title] > Drafts.
  3. Select the file you want to download. You will be taken to the file’s page.
  4. Click on the file’s name to download it.
  5. Change the file’s status: click State: Pending review and select Retract. (It changes to State: Internal draft.)
File:Image3.png

Uploading a chapter after review

  1. Be sure you are signed into the TDF NextCloud server..
  2. Go to the required folder: LibreOffice > English > [book title] > Feedback.
  3. On the menu bar above the list of files, click Add new and then click File from its menu.
  4. On the Add File page, type the title and (optionally) a description of the document.
  5. Click the Browse button to open a standard file browser window. Find and select the file on your computer, then click Open.
  6. Back on the Add File page, click Save to upload the file to the NextCloud server.
  7. Set the file’s status to Pending review (see “Submitting a chapter for review” on page 7.
  8. Report what you have done, and the location of the file, to the documentation team’s mailing list (documentation@global.libreoffice.org).

Publishing a chapter

  1. Be sure you are signed into the TDF NextCloud server.
  2. Go to the required folder: LibreOffice > English > [book title] > Published.
  3. On the menu bar above the list of files, click Add new and then click File from its menu.
  4. On the Add File page, type the title and (optionally) a description of the document.
  5. Click the Browse button to open a standard file browser window. Find and select the file on your computer, then click Open.
  6. Back on the Add File page, click Save to upload the file to the NextCloud server.
  7. Change the file’s status: click State: Pending review and select Publish externally. (It changes to State: externally visible.)
  8. Report what you have done, and the location of the file, to the documentation team’s mailing list (documentation@global.libreoffice.org).
File:Graphics7.png
Im-jabber.svg

Note:
In addition, add the chapter ODT and PDF to the wiki by editing the Publications page and then uploading the files. https://wiki.documentfoundation.org/Documentation/Publications

Tracking progress using the wiki

When you are working on a chapter, please place your initials and the date in the Checkout column of the appropriate table on the Documentation Development wiki page, http://wiki.documentfoundation.org/Documentation/Development/UserGuideTasks

When you return the file to the NextCloud server, please remove your initials and date from the Checkout column and add your initials and the date to the appropriate column (reviewed, edited).

For more information

If you have any questions, remember the Documentation Team mailing list, documentation@global.libreoffice.org

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