Documentation/DocumentationTeamInfo/UsingAuthorsWebsite

From The Document Foundation Wiki
Jump to: navigation, search

Template:TopMenu/en Template:Menu/en Template:Menu.Documentation/en

Other languages:
Documentation Contributors’ Guide
Chapter 3 Using the Documentation Team Website
Previous: Chapter 2 Up: Preface Next: Chapter 4
THIS PAGE IS CURRENTLY BEING EDITED

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 Organizing workflow through folders diagram below. See also the Tracking progress section below for details of the file naming convention used for tracking the progress of a file.

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 mailing list <documentation@global.libreoffice.org> .
  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 mailing list <documentation@global.libreoffice.org> .
  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 reports what has been done, together with the location of the file to the documentation team’s mailing list <documentation@global.libreoffice.org> .
  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 mailing list <documentation@global.libreoffice.org> .
  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 final check on file and adds a PDF copy to 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.)
Im-jabber.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
Im-jabber.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 between them 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)
  1. 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 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 “Notes” where appropriate.

5. Upload the result to the Work In Progress folder for the new 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 mailing list <documentation@global.libreoffice.org> .

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:

  • Chapter 2, Producing LibreOffice User Guides, includes file naming conventions and instructions for creating and inserting images, indexing, and so on.
  • Chapter 4, Style Guide, includes writing style, word usage, and other instructions.
  • Chapter 5, Using the LibreOffice Chapter Template, includes instructions for installing the template and creating a new document from it, and the use of the page, paragraph, character, and other styles included in the template.

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 mailing list (documentation@global.libreoffice.org).

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 , 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. The section here 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 mailing list <documentation@global.libreoffice.org> 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 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 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).

Im-jabber.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 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.