Using the LibreOffice Documentation Team Website

    From The Document Foundation Wiki
    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

    Figure1: Overview of Chapter development.

    Figure 1 above is a very generalized outline of the development process. There might be times or situations when it is necessary to skip or vary some of the steps shown.

    Workflow description

    Refer to Figure 1 above and the diagram in #Organizing workflow through folders.

    There are two situations where a new guide chapter is created:

    1. The equivalent chapter of a previous edition of a guide is being updated to cover a more recent version of the software.
    a) The Author takes a copy of the previously published edition of the chapter.
    b) Applies the most recent chapter template to the document.
    c) Revises the document content to make it relevant to the appropriate software version.
    2. A new chapter is being created.
    a) The Author opens a copy of the most recent chapter template.
    b) Writes the new chapter, applying the styles defined in the chapter template.

    In either of the above cases the same procedure is is then followed:

    1. The Author uploads the new document to the guide's Work In Progress folder on the NextCloud website, updates the Guide Status spreadsheet. Then submits it for 1st review, by reporting what has been done, together with the location of the file to the Documentation Team’s forum.
    2. A Reviewer downloads a copy of the document from the guide's Work In Progress folder on the NextCloud website, updates the Guide Status spreadsheet on NextCloud and reports that the file has been taken for review to the Documentation Team’s forum.
    3. With Track Changes > Record turned on, the Reviewer checks and revises the document, changes the file name and uploads the reviewed document to the guide's Work In Progress folder on the NextCloud website. Then the Reviewer reports what has been done, together with the location of the file to the Documentation Team’s forum.
    4. At the same time as the reviewed document is uploaded to the NextCloud Work In Progress folder, the previous copy of the document is moved from the Work In Progress folder to the Archive folder.
    5. Steps 2, 3 and 4 are repeated for the 2nd review.
    6. The Author downloads a copy of the document from the guide's Work In Progress folder, accepts/rejects edits, makes any other changes needed, optionally submits for another review, or uploads revised file to the Published folder, updates the Guide Status spreadsheet. Then reports what has been done, and the location of the file, to the Documentation Team’s forum.
    7. At the same time as the final document is uploaded to the NextCloud Published folder, the previous copy of the document is moved from the Work In Progress folder to the Archive folder.
    8. The Publisher (coordinator) does a final check on the file and adds a PDF copy to the Published folder.
    9. When all completed chapters are in the Published folder, the publication process begins. (See Chapter 2, Producing LibreOffice User Guides for more information about the publishing process.)
    Note pin.svg

    Note:
    At this point the Work In Progress folder will be empty and should be deleted.

    Organizing workflow through folders

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

        English
            [book name (For example: Calc Guide)]
                [version (For example: 6.4)]
                    Archive
                    Work In Progress
                    Published
                    Source files (pre draft)
                    Supplement (eg. Images, Examples, etc.)
                Guide Status.ods
    

    Navigating the NextCloud website

    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 2. The visible folders may vary depending on the permissions you have been assigned.

    Figure2: Initial screen on TDF NextCloud website

    1. Click on LibreOffice Documentation to display a screen similar to Figure 3.

    Figure3: Folders in LibreOffice Documentation

    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 (see Figure 4 for an example).

    Figure4: LibreOffice versions of a user guide

    4. Next you will reach a screen with folders for Archive, Work In Progress and Published; occasionally some supplementary folders; and a Guide Status spreadsheet (Figure 5).

    5. Click on a folder to go to a list of files. Figure 6 gives an example. The controls to download and upload files from this screen are described in the following sections.

    Figure5: Folders and status spreadsheet for a user guide
    Note pin.svg

    Note:
    The “Readme.md” is a NextCloud control file and can be safely ignored.

    Creating a new user guide chapter

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

    1. New chapter based on an existing chapter (for example, when updating information for a new edition of the guide based on a new version of LibreOffice).

    2. 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 version of LibreOffice.

    1. Download a copy of the ODT file for the published chapter for the previous version of the guide.

    2. Rename the copy according to our file naming convention (see Chapter 2, Producing LibreOffice User Guides).

    3. If necessary, download a copy of the latest user guide chapter template, which you can get from LibreOffice Documentation > English > Contributor Resources in TDF NextCloud (see Figure 7), update the document to use. (See Chapter 5, Using the LibreOffice Chapter Template, for instructions.)

    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 reorganizing or rewriting – then it is acceptable to leave change tracking off. In either case add Comments where appropriate.

    5. Upload the result to the Work In Progress folder for the new guide on the TDF NextCloud server:

    a) Sign into TDF NextCloud.
    b) Go to LibreOffice Documentation > English > [ title] > [version] > Work In Progress.
    c) Click on the + icon in the top of the screen. (See Figure 6).
    i) Select Upload File.
    ii) 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” below.

    7. Report what you have done, and the location of the file, to the Documentation Team’s forum.

    Figure6: Uploading a file to NextCloud

    Creating a completely new chapter

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

    1. Create a draft document based on the template, which you can get from LibreOffice Documentation > English > Contributor Resources in TDF NextCloud (see Figure 7). 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 document to the guide Work In Progress folder, as described in step 5 of #Creating a new chapter based on an existing chapter above.

    Figure7: Downloading the chapter template

    4. Submit the document for review. See #Submitting a chapter for review.

    5. Report what you have done, and the location of the file, to the Documentation Team’s forum.

    Submitting a chapter for review

    When the new chapter is ready for review:

    1. Be sure the file is named according to our naming convention (see Chapter 2, Producing LibreOffice User Guides).
    2. Sign into the TDF NextCloud server.
    3. Go to the Work In Progress folder for the guide version.
    4. Upload the file as described in step 5 of #Creating a new chapter based on an existing chapter.
    5. Go back to the version folder for the guide, 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 forum.

    Reviewing a chapter

    Refer to Chapter 2, Producing LibreOffice User Guides, for information on what to look for when reviewing a chapter. This section only 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. Sign into the TDF NextCloud server.

    2. Go to the required folder: LibreOffice > English > [ title] > [version] > Work In Progress. (See Figure 8.)

    Figure8: Downloading a file from NextCloud

    3. Select 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.

    5. Click Download to download the file to your computer.

    6. Go back to the version folder for the guide, click on the Status spreadsheet for online editing, and proceed as described in #Tracking progress using the Status spreadsheets.

    7. Report to the Documentation Team’s forum that you have taken the chapter for review.

    Uploading a chapter after review

    1. Be sure you are signed into the TDF NextCloud server.

    2. Go to the required folder: LibreOffice > English > [ title] > [version] > Work In Progress.

    3. Upload the file as described in step 5 of #Creating a new chapter based on an existing chapter.

    4. After uploading the reviewed chapter, click the three dots to the right of the previously updated/reviewed copy of that chapter and click Move or copy. Click [version] in the folder hierarchy, then click the Archive folder and click the Move to Archive button. It is recommended to wait until the move is complete before taking any further actions.

    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 forum.

    Publishing a chapter or a book

    Refer to Chapter 2, Producing LibreOffice User Guides, for information on what to check before publishing a chapter. The section here only describes how to use the TDF NextCloud website when publishing a chapter.

    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 forum.
    Note pin.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 guide has a Status spreadsheet in the LibreOffice > English > [ title] > [version] folder.

    When you are working on a chapter, please place your initials in the Checked Out By 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 column and add your initials and the date to the appropriate column (reviewed, edited).

    Note pin.svg

    Note:
    The date format to be used is ISO 8601 without any separating dots, dashes or slashes. The last day of October 2020 would be represented by 20201031

    For more information

    If you have any questions, remember the Documentation Team’s forum

    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.