Documentation/Dashboard/Producing User Guides

From Apache OpenOffice Wiki
< Documentation‎ | Dashboard
Revision as of 20:59, 22 September 2010 by Jeanweber (Talk | contribs)

Jump to: navigation, search

Topics for guide to producing OOo user guides (not necessarily in sequential order)


  • Create screenshots
  • Create other illustrations
  • Label screenshots and other illos (add callouts)
  • Insert images
  • Cross-reference to figures, tables, headings
  • Cross-reference to other documents


How to set up OOo for working with user guides

When working on OOo user guides, you may need to change a few option settings. You also need to download and install some files, and you may wish to create some AutoText entries.

Change View options

The setting for one View option (Icon size and style) is important for consistency when capturing screens to illustrate our documents; another setting is a matter of personal preference.

Go to Tools > Options > OpenOffice.org > View and make sure the choices for Icon size and style in the User Interface section near the top are Small, Galaxy (default).

If you have been using OOo for some time, you know that the method of marking a text or graphics selection changed from reversed color (typically white text on a black background) to a pale background. Some people like the new display but if you prefer reversed color, deselect the Transparency option under Selection.

Choosing View options for working with OOo user guides.

Change Memory options

User guide chapters often contain a lot of images, and a full book may have several hundred. When you open one of these documents in OpenOffice.org, it may take several minutes to fully load and display all the images. Later you may discover that images seem to disappear from the document. In fact, the images are still in the file even if you cannot see them on screen or in a PDF created from the file.

This problem can be cured by changing the default memory settings for OpenOffice.org, to make more memory available to OOo, to increase the time that objects remain in memory, and to increase the number of cached objects. To offset the extra memory needed for large numbers of objects, you can usually decrease the memory for each object (images in our documents are typically less than 1 MB) and decrease the number of Undo steps.

Template:Documentation/Note

To change memory settings, go to Tools > Options > OpenOffice.org > Memory. Here are some suggested settings for working with OOo user guide files:

  • Undo
    • Number of steps: 20
  • Graphics cache
    • Use for OpenOffice.org: 256 MB
    • Memory per object: 1.0 MB
    • Remove from memory after: 1:00 hh:mm
  • Cache for inserted objects
    • Number of objects: 350
Choosing Memory options for working with OOo user guide files

Download and install chapter template

The template we use when writing chapters of the user guides is located here: http://www.oooauthors.org/english/userguide3/res3/OOo3_chapter_template.ott.

  1. Download the template and save it anywhere on your computer.
  2. Documentation caution.png If your browser gives you a choice of Open with OpenOffice.org or Save File, choose Save File. Otherwise, the template opens as an untitled ODT (text) file; if you then save this file, it is saved as an ODT file, not as an OTT (text template) file.
  3. Now import the template into an OOo template folder:
    1. Choose File > Templates > Organize from the menu bar.
    2. In the Template Management dialog, select the folder into which you want to import the template. Usually this is My Templates but you may wish to create a separate folder for OOo User Guides.
    3. Click the Commands button and choose Import Template from the drop-down menu. A standard file browser window opens.
    4. Find and select the template that you just downloaded and click Open. The file browser window closes and the template appears in the selected folder.

Template:Documentation/Note

Download and install Template Changer extension

Using the Template Changer extension can make some work much easier, so we recommend you install it while setting up OOo to work on the user guides.

Using Template Changer, you can assign a new template to the current document or to a folder of documents. All styles and formatting will be loaded from that template and the document will behave as it was created using that template.

  1. Download the extension from here: http://extensions.services.openoffice.org/en/project/templatechanger and save it anywhere on your computer.
  2. Choose Tools > Extension Manager and click the Add button. A standard file browser opens.
  3. Find and select the extension you just downloaded and click Open.
  4. You will be asked to accept a license agreement.
  5. When the installation is complete, the extension is listed in the Extension Manager.
  6. Close the Extension Manager.
  7. To activate the Template Changer, close OpenOffice.org and reopen it. You will now find two new items in the File > Templates menu: Assign template (Current document) and Assign template (folder).

Create AutoText entries for Tip, Note, Caution, and data tables

Tips, Notes, and Cautions use tables for layout. In addition, we sometimes include tables of data.

The chapter template provides examples of Tip, Note, Caution, and data tables. You can copy and paste these tables as needed, but you may find it easier to insert them using AutoText. With AutoText, once you have set up the entries, you just have to type the shortcut (for example, tip or note) and press F3 to insert one. In each case, the formatting of the table is preserved: column widths, text, and any graphics. You can then add or change anything you want in the table.

Here is how to set up an AutoText entry for a Note:

  1. Open the chapter template in OOo. Go to the last page, where you will find samples of a tip, a note, and a caution. (A sample data table is on page 13 of the template.)
  2. Select the entire Note table.
  3. Press Ctrl+F3, or choose Edit > AutoText from the menu bar, to open the AutoText dialog box.
  4. In the Category box, select My AutoText. Type Note in the Name box. OOo suggests N as the Shortcut; you may wish to change this, for example to Note.
  5. Click the AutoText button on the right and choose New. The Note table is saved as AutoText.
  6. Click Close to close the AutoText dialog box and return to the document.

Repeat for a Tip, a Caution, and a table of data.

How to create a new chapter from the template

To create a new document from the chapter template:

  1. Do one of the following to open the Templates and Documents dialog box:
    • From the Start Center, choose Templates...
    • From the menu bar, choose 'File > New > Templates and Documents.

    Template:Documentation/Note

    Creating a new document from the OOo chapter template.
  2. In the box on the left of the Templates and Documents dialog box, click the Templates icon if it is not already selected. A list of template folders appears in the center box.
  3. Double-click the folder that contains the OOo3_chapter_template. (In our example, this is in the My Templates folder.) A list of all the templates contained in that folder appears in the center box.
  4. Select the OOo3_chapter_template.
  5. Click Open. The Templates and Documents dialog box closes and a new document based on the OOo3_chapter_template opens in Writer.

The new document includes all the text and graphics contained in the template. Much of this material must be modified or deleted, as follows:

  1. On the title page:
    • Change [Component] to the name of book this chapter will be in, for example Base, Calc, Writer. If you are using the template for some other document (such as a HowTo or Tutorial) that is not part of a user guide, delete the words [Component Guide] but leave the paragraph marker so the rest of the text on the page is spaced out correctly.
    • Change n to the chapter number. Make sure the chapter number retains the character style of OOoChapterNumber. The best way to do this is to highlight the n and type the number to replace the n.
    • Change Type Chapter Name Here to the name of the new chapter. Make sure this line retains the two blank spaces before the first word. These blank spaces are required for correct spacing of text in the footer of the compiled book file.
  2. Choose File > Properties and go to the Description page. In the Title field, replace OOo3_chapter_template with the name of the chapter that you put on the title page. Delete the Revision information in the Comments box. Click OK.
  3. On the Copyright page:
    • For a new chapter, change 2005-2010 to the current year only.
    • Add your name in the Authors section.
    • Add anything you wish to the Acknowledgments section.
    • In the Publication date and software version section, replace [N.n] with the version of OOo used for this chapter.
    • Other changes to the page will be made later.
  4. We recommend you read the document before beginning to write; it explains what styles to use for what purpose. You may wish to retain some or all of the contents for reference while you are writing and delete them only when ready to upload the chapter for review.
  5. If you have not made AutoText from the Tip, Note, Caution, and data tables, now is a good time to do that. Otherwise, you may wish to keep those examples in the file so you can copy them as needed.

Before you continue, save the file using the naming convention for draft documents.

Just before uploading a chapter for review, do these things:

  1. Update the table of contents: hover the mouse cursor over the TOC, right-click, and choose Update Index/Table from the context menu.
  2. On the Copyright page, in the Publication date and software version section, replace [date] with the current date.

How to update the chapter template from the website

When the chapter template is updated, a note will be sent to the Authors mailing list. It is a good idea to get a copy of the revised template to replace the one on your computer.

If you have been away for awhile or don't check the Authors list very often, you may wish to check whether you have the latest version of the template and update it on your computer.

[more to be written]

How to update a chapter from a changed template

[To be written]

How to index a user guide chapter

[To be written]

  • Insert index entries
  • Edit index entries

How to write and edit common topics

[To be written]

  • Use variables and other fields
  • Use conditional text, hidden paragraphs
  • Insert common topics into a chapter
    • Use sections

How to publish a chapter

When you have decided that a chapter is ready for publishing, do the following:

  1. Make a final pass to check page breaks and make any necessary changes. (Use the keep-with-next attribute, not manual page breaks, and/or change the sequence of text and figures.)
  2. Verify that the first item in the first numbered list in the chapter is explicitly set to start at 1 (this is to make sure the chapter works properly when it is a subdocument in a master document for a compiled book). To do this:
    1. Right-click on the first list paragraph and choose Paragraph.
    2. Go to the Outline & Numbering tab. In the Numbering section, select the checkbox for Restart at this paragraph and select the checkbox for Start with, making sure the number is 1.
    3. Click OK to save the change.
  3. Update the ToC. Make sure there is no (alphabetic) index at the end of the chapter.
  4. On the copyright page, insert the current date and the software version. Verify that the correct email address for OOoAuthors, and the correct URL for published chapters (in the footer), are shown.
  5. Save the ODT file with the correct file name, using the naming convention for published chapters (see below).
  6. Export the file to PDF, using these settings:
    • On the General tab, select Export bookmarks.
    • On the Initial View tab, in the Page layout section, select Continuous facing.
  7. Upload both files to the Published Chapters folder for the relevant book, overwriting any files of the same names that are already there, and change their state to "externally visible".
  8. Tell the Authors list that you have published the chapter.
  9. Update the relevant page in this folder.
  10. Log in to the OpenOffice.org wiki and replace the chapter file (PDF). To do this:
    1. Use an address similar to http://wiki.services.openoffice.org/wiki/File:0401DG3-IntroducingDraw.pdf to get to the File History wiki page for the chapter.
    2. Choose Upload a new version of this file.
    3. On the Upload File page, browse for the chapter file, type something in the File Changes box (usually "corrected typos" or "updated for version x.x" or similar is sufficient). Select the Ignore any warnings checkbox and click the Upload file button.
  11. Go to the User Guides page. Edit that page to show the publication date and file size for the revised chapter.

Naming convention for published chapters

To ensure that chapters and books are listed correctly on the Documentation Project's website, file names take the following form:
AABBCC3-Name, where
AA=book number, BB=chapter number, CC=book initials, 3=OOoVersion 3, Name=Chapter name.

Book number and initials:
01 = GS = Getting Started
02 = WG = Writer Guide
03 = CG = Calc Guide
04 = DG = Draw Guide
05 = IG = Impress Guide
06 = MG = Migration Guide
07 = BG = Database Guide

The chapter or book name is given in full; each word begins with a capital letter and there are no spaces between words.

For example, the third chapter of the Writer Guide, Working with Text, has the following file name:
0203WG3-WorkingWithText.pdf

Note: The "chapter number" for a full book is 00. Thus the file name for the Getting Started book is
0100GS3-GettingStarted.pdf

How to compile and publish a book using a master document

The user guides being produced by OOoAuthors consist of a set of individual chapter files, plus a master document file that combines the chapter files into a book.

The chapter files have been designed so that the copyright page and the chapter's table of contents pages are in a conditional section which is hidden when the chapter is part of a book.

The master document file contains a copyright page listing all the authors of all the chapters in the book and a table of contents for the full book, a TOC for the entire book, and an index for the entire book.

Compiling the book

When you have published several changed chapters in a completed book, you need to regenerate the full book. To do this:

  1. Be sure the *.odt files for the latest version of all chapters are in the Published Chapters folder for the book.
  2. Download all the *.odt (chapter) files and the *.odm (master document) file and place them in a folder on your computer.
  3. If any new names have been added to the Authors section of the copyright page of any chapter, take a note of them.
  4. Open the *.ODM (master doc) file for the book. When asked "Update all links?" click Yes.
  5. Wait while the file loads and paginates; this may take several minutes. To avoid errors, do not do anything with the file until it finishes paginating; do not even scroll through the file.
  6. If any chapter files do not load, you may need to edit the path for those files in the Navigator for the master document. Problem files are shown in red in the Navigator.
  7. When all the files have loaded and the book has finished paginating, regenerate the table of contents and index by right-clicking on each of them and choosing Update from the pop-up menu.
  8. Check that the Authors section of the master document's copyright page includes all the authors for the changed chapters.
  9. Check that the information in File > Properties is correct.
  10. On the copyright page, change the publication date to the current date, change the OOo version information to the version covered by the book, and check that the email address for OOoAuthors and the URL for the published chapters (given in the footer) are correct.
  11. Check that the footers show the correct information: book title on left-hand (even) pages and chapter title on right-hand (odd) pages.
  12. Check that the first item in the first numbered list in each chapter from Chapter 2 on is numbered "1" as it should be; it may continue the numbering from the last list in the preceeding chapter. If necessary, OPEN EACH PROBLEM CHAPTER and explicitly restart at "1" the number of the first list paragraph in the first numbered list in each chapter. To do this:
    1. Right-click on the first list paragraph and choose Paragraph.
    2. Go to the Outline & Numbering tab. In the Numbering section, select the checkbox for Restart at this paragraph and select the checkbox for Start with, making sure the number is 1.
    3. Click OK to save the change.
  13. Check that the copyright pages and TOCs of the individual chapters do NOT appear in the book, and that the [Component} Guide paragraph does not appear on the individual chapters' title pages. Fix in the problem chapter as needed.
    Note: Do not make changes to chapters within a master document, because they are lost when you close the file.
  14. Review the compiled index. If any entries need to be changed, open the relevant chapter and make the changes in the chapter file, not in the index visible in the master document. See also How to index a user guide chapter.
  15. If you have made any changes to the chapters, reload the master document and wait for it to paginate again. Recheck to ensure all is well. Repeat as needed.
  16. A bug in OOo (or a gremlin in some of our older files) causes some figure and table numbers, and some cross-references to figures and tables, to be incorrect in the master doc, even though they are correct in the subdocs. You really need to go through the entire book, checking and fixing any incorrect figure numbers or references. This is a major PITA, so we do not regenerate the books very often. To fix the x-refs, open the subdoc itself, delete the wrong x-refs, and recreate them—even though they appear to be correct in the subdoc. This will usually cure the problem (for that x-ref) in the master document. After editing the subdocs, reload the chapters into the master document.
  17. When all changes have been done, regenerate the TOC and index in the master document. Save the master document.
  18. Create one ODT file from the master doc and its subdocs, as explained in Chapter 13 (Working with Master Documents) in the Writer Guide. Remove the links to the sections, to embed the text into the ODT file. Then either remove the write protection on the sections or remove the sections completely (the contents remain; only the section markers are removed). Name this ODT file according to the naming convention for published documents (see below).
  19. Check the ODT file you just created again to make sure the cross-references, page breaks, list numbering, and other potential problems are fixed.
  20. Select File > Export as PDF. Choose the following settings:
    • On the General tab, select Export bookmarks.
    • On the Initial View tab, in the Page layout section, select Continuous facing.
  21. Name the PDF according to the naming convention for published documents (see below).

Publishing the book

  1. Upload the changed master doc file, the ODT file containing the full book, and the PDF file to the Published Chapters folder for the book, replacing the previous version of the master doc and the book. Set the state of the master doc (.odm) and the PDF to "externally visible" but set the state of the ODT as "internally published".
  2. If any chapter files have been modified during book production, upload the changed files to the Published Chapters folder for the book, replacing the previous versions. Set the state to "externally visible".
  3. Log in to the OpenOffice.org wiki and replace the book file (PDF). To do this:
    1. Use an address similar to http://wiki.services.openoffice.org/wiki/File:0100GS3-GettingStartedOOo3.pdf to get to the File History wiki page for the book.
    2. Choose Upload a new version of this file.
    3. On the Upload File page, browse for the book file, type something in the File Changes box (usually "corrected typos" or "updated for version x.x" or similar is sufficient). Select the Ignore any warnings checkbox and click the Upload file button.
  4. Go to the User Guides page. Edit that page to show the publication date and file size for the revised book.
  5. For the convenience of translators, create a zip file containing the master document (ODM) and all the individual chapters (ODT). Create another zip file containing all the individual PDFs. Upload these zip files to o the Published Chapters folder for the book, replacing the previous versions. Set the state to "externally visible".
  6. Tell the Authors list that you have republished the book.

Naming convention for published books

To ensure that chapters and books are listed correctly on the Documentation Project's website, file names take the following form:
AA00CC3-Name.pdf, where
AA=book number, 00=book (these are zeros), CC=book initials, 3=OOo3, Name=Chapter name.

Book number and initials:
01 = GS = Getting Started
02 = WG = Writer Guide
03 = CG = Calc Guide
04 = DG = Draw Guide
05 = IG = Impress Guide
06 = MG = Migration Guide
07 = BG = Database Guide

The book name is given in full; each word begins with a capital letter and there are no spaces between words. So for example, the file name for the Getting Started with OOo3 book is
0100GS3-GettingStarted.pdf

Personal tools