Using the LibreOffice Documentation Team Website
TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate
| 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
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:
- 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.
- 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.
- 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.
- 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.
- Steps 2, 3 and 4 are repeated for the 2nd review.
- 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.
- 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.
- The Publisher (coordinator) does a final check on the file and adds a PDF copy to the Published folder.
- 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:
|
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
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.
1. Click on LibreOffice Documentation to display a screen similar to Figure 3.
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).
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.
|
Note:
|
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.
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.
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:
- Be sure the file is named according to our naming convention (see Chapter 2, Producing LibreOffice User Guides).
- Sign into the TDF NextCloud server.
- Go to the Work In Progress folder for the guide version.
- Upload the file as described in step 5 of #Creating a new chapter based on an existing chapter.
- 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.
- 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.)
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.
- Be sure you are signed into the TDF NextCloud server.
- Go to the required folder: LibreOffice > English > [book title] > [version] >Published.
- Upload the file as described in #Creating a new chapter based on an existing chapter.
- 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.
- Report what you have done, and the location of the file, to the Documentation Team’s forum.
|
Note:
|
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:
|
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.