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.


Documentation Contributors’ Guide
Chapter 3 Using the Documentation Team Website
Previous: Chapter 2 Up: Preface Next: Chapter 4

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 LibreOffice Documentation website (https://documentation.libreoffice.org) in addition to The Document Foundation’s wiki (https://wiki.documentfoundation.org/Documentation/Publications).

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.4, for example)]
                Archive
                Draft
                Feedback
                Published
                Source files (pre draft)
                Images
                Guide Status.ods

Navigating the NextCloud website

NEED TO FIND PIX TO ILLUSTRATE SOME STEPS?

When you log in to the TDF NextCloud website using the single sign-on procedure described in Chapter 1, you will usually see a screen similar to the one shown in Figure 1. The visible folders may vary depending on the permissions you have been assigned.

  1. Click on LibreOffice Documentation to display a screen similar to Figure 2.
  2. Click on English.
  3. On the next screen, click on the relevant user guide to display a list of the LibreOffice versions for which user guides have been produced or are being working on.
  4. Next you will reach a screen with folders for Archive, Drafts, Feedback, and Published; often some other folders; and a Guide Status spreadsheet.
  5. Click on a folder to go to a list of files. The controls to download and upload files from this screen are described in the following sections.

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.

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

Creating a new chapter based on an existing chapter

This is the most common scenario for people working on LibreOffice user guides.

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. If necessary, update the document to use the latest user guide chapter template. See Chapter 5 for instructions.
  3. Rename the copy according to our file naming convention (see Chapter 2, Producing LibreOffice User Guides).
  4. Revise the chapter as needed, normally with change tracking on (see Chapter 2, Producing LibreOffice User Guides). If the changes to the chapter are extensive – especially if they include reorganising or rewriting – then it is acceptable to leave change tracking off.
  5. Upload the result to the Draft folder for the new book on the TDF NextCloud server.
    1. Sign into TDF NextCloud (https://auth.documentfoundation.org/saml/).
    2. Go to LibreOffice Documentation > English > [book title] > [version] > Draft.
    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.
  6. Submit the document for review; see Submitting a chapter for review section below.
  7. Report what you have done, and the location of the file, to the Documentation Team’s mailing list (documentation@global.libreoffice.org).

Creating a completely new chapter

This scenario is less common than creating a chapter based on an existing chapter, described above.

Location of latest template file in Nextcloud
  1. Create a draft document based on the template (currently LibreOffice_6.x_Template.ott), which you can get from LibreOffice Documentation > English > Contributor Resources in TDF NextCloud. Other chapters in this guide provide relevant information:
  2. Save the file using the file naming convention described in Chapter 2, Producing LibreOffice User Guides.
  3. After writing the chapter, upload the draft to the appropriate folder, as described in #Creating a new chapter based on an existing chapter above.
  4. Submit the document for review; see Submitting a chapter for review below.
  5. Report what you have done, and the location of the file, 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:

  1. Be sure you are signed into the TDF NextCloud server.
  2. Be sure the file is named according to our naming convention (your initials and the date).
  3. Go to the Feedback folder for the book and LibreOffice version.
  4. Upload the file as described in #Creating a new chapter based on an existing chapter.
    Uploading a file to NextCloud
  5. Go back to the version folder for the book, click on the Status spreadsheet for online editing, and proceed as described in #Tracking progress using the Status spreadsheets.
  6. Report what you have done, and the location of the file, to the documentation team’s mailing list (documentation@global.libreoffice.org).

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 Documentation > English > [book title] > [version] > Drafts.
  3. Find the file you want to review. DO NOT click on the filename, as that will open it for editing online. DO NOT edit files online. (Exception: the Status spreadsheet for each book.)
  4. On the right is a column containing three dots by each file. Click the dots by the relevant filename to drop down a list of actions.
    Downloading a file from NextCloud
  5. Click Download to download the file to your computer.
  6. Go back to the version folder for the book, click on the Status spreadsheet for online editing, and proceed as described in #Tracking progress using the Status spreadsheets.

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] > [version] > Feedback.
  3. Upload the file as described in #Creating a new chapter based on an existing chapter.
  4. Go back to the version folder for the book, click on the Status spreadsheet for online editing, and proceed as described in #Tracking progress using the Status spreadsheets.
  5. 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 or a book

  1. Be sure you are signed into the TDF NextCloud server.
  2. Go to the required folder: LibreOffice > English > [book title] > [version] >Published.
  3. Upload the file as described in #Creating a new chapter based on an existing chapter.
  4. Go back to the version folder for the book, click on the Status spreadsheet for online editing, and proceed as described in #Tracking progress using the Status spreadsheets.
  5. Report what you have done, and the location of the file, to the documentation team’s mailing list (documentation@global.libreoffice.org).
Im-jabber.svg

Note:
For a compiled book, also 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 Status spreadsheets

Each book has a status spreadsheet.

When you are working on a chapter, please place your initials in the Checkout column and the date you expect to return the file.

When you return the file to the NextCloud server, please remove your initials and date from the Checkout columns 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.