On rare occasions (very few) you will need to change the content of a numbered legend and laying out the contents of a table is not a so hard work.
Hello Antonio
I know how to insert blank and borderless tables. I did think of using tables, but found that columns were better.
The problem with using tables is that you have to manually format the contents in each table cell to balance the contents if there is change in number of legend items or the number of cells in the table. Manual formatting increases the risk of errors being created.
Columns automatically reflow the contents if there is a change in column format. That is if the number of legend items is increased or decreased; or increasing or decreasing the number of columns.
Regards
Peter Schofield
psauthor@gmail.com
Technical Writer, LO Documentation Team
Each technique has its advantages and disadvantages, working with sections you have to add a paragraph break before each section to separate them from the content of the document, otherwise the content of the section is left without separation from the rest of the text and the images overlap with the content of the section.
-
Once the content is distributed in the tables, the numbering of legend items changes the same as in the sections: automatically.
-
In both tables and sections, adjustments must be made for the width of the table or section or the width of the columns, although the methods are different.
You may think that using sections is better than using tables, but that’s your opinion. Mine is the opposite and I also rely on the export to HTML
I would also like to know the opinions of the rest of the documentation team (they seem to be very quiet)
Several opinions can clarify the standard that should be followed in the guides for this format of numbered legends and in this way unify the format of the guides.
If that is what is intended.
Hello Antonio
I think we have to agree to disagree (a confusing English phrase).
I do prefer to use columns for this type of format. However, I will try your solution of using tables and I am even going to try a text box, but I think a text box will be too restrictive.
I shall be using the template from the Sanity Check extension to create a new Chapter Template Instruction and a User Guide Template Instruction as separate files. Legends will be included.
Regards
Peter Schofield
psauthor@gmail.com
Technical Writer, LO Documentation Team
I think that a text box is not a good idea because it does not support styles and is a new element on the guides.
Consider that a template has to be prepared with the strictly necessary elements (Logo, sections, index) for the author to start writing, without the author having to delete anything.
A template with other elements is not productive.
- Instructions on the use of writing styles or techniques should be in a separate, accessible document or included in the contributor guide
One reason why I was not sure about text boxes abd will not be using.
Regards
Peter Schofield
psauthor@gmail.com
Technical Writer, LO Documentation Team
It’s very easy to create a master guide document with SanityCheck’s built-in templates.
Procedure:
- Create a new Master Document with LO_UG_Master_2Xx_EN Template
File >New>Templates - Replace the cover image
Right Clic in the cover image and choose Replace on the popup menu and Chose your cover image.
(The template uses a First page Stylle wich is diferent of the First page of the Chapters). - Open your File manager, on the Filemanager go to the directory where the chapters are saved, select all chapters and drop them into the Writer Window.
- Order the chapters if necessary
- Create a new cover document with LO_UG_Backcover_2Xx_EN Template
File > New > Templates- Replace the Backcover image and the text into the Textbox
- Save the Backcover document and add it to the new Master Document.
(BackCover template use a left page style so always it will be a left page in the printed edition)
NO extra pages styles are necessary
maybe a dedicated topic, or wiki, or bugzilla … ? 
Hello Antonio
A few comments on the template.
LO Writer compatibility options
Two options in Tools > Options > LibreOffice Writer > Compatibility (macOs LibreOffice > Preferences > LibreOffice Writer > Compatibility) must not be selected because these options create page formatting errors and leave blank spaces on the pages. The options are as follows:
Add spacing between paragraphs and tables
Add paragraph and table spacing at top first page and page breaks.
All previous LO chapters and user guides have been created without the above options being selected.
LibreOffice logo
The LibreOffice logo at the top of the page is incorrectly positioned. In the Image Properties dialog on the Wrap page, the Spacing Top measurement has been set 1.92cm. In all previous versions of LO Chapters and User Guides, the Spacing Top measurement has been set to 0.00cm. The logo the appears at the top of the title page.
Chapter title
In all previous versions of LO Chapters and User Guides, the chapter title has been text using the paragraph style Title. There is no requirement for the chapter title to be created using a field. The chapter title only appears once in a chapter.
There may be more comments on the template as work through the template when updating the chapters.
Regards
Peter Schofield
psauthor@gmail.com
Technical Writer, LO Documentation Team
Thank you Antonio for the info of how to create a master document.
I will be honest, I have never created master documents. The Draw guide will be my first attempt.
Regards
Peter Schofield
psauthor@gmail.com
Technical Writer, LO Documentation Team
As you say, this “compatibility” is configured in Options but it is a user configuration of LibreOffice
- This is NOT configured by any template or document
In older versions of the guides the logo was separated from the top edge of the text area of the page.
- This leaves all the content on the first page centered, which I think is more visually accurate.
You can use fields for Chapter number and Chapter Title or not .
In SanityCheck extension, these custom document properties are used to automatically fill the document title (in the document properties) and also for the footers. So I have taken advantage of them for use on the first page
- This is indicated in the SanityCheck documentation.
Hello Antonio
LO Writer compatibility options and LibreOffice logo
I will use the template you have created and leave the compatibility options and chapter front page as per template for all new documents. That is when I upgrade to the new version of LO.
Chapter title
I will use fields as per the template to help with your sanity check for new documents.
Regards
Peter Schofield
psauthor@gmail.com
Technical Writer, LO Documentation Team
In the Spanish documentation team we are working on the Draw 7.6 guide and rearranging images so that they appear in a logical order as close as possible to their respective descriptions.
I have noticed that in version 24.2 of the English guide the example figures appear mostly grouped,
and often before the Heading that contains the description of the example figure.
- This can be seen for example on pages 176 and 177
I understand that the chapters must be laid out so that the guide contains the fewest possible pages, but the way the figures are placed seems somewhat chaotic to me and I think that they can sometimes cause confusion.
- I think that the figures should be placed as close to the text that describes them and never before the heading related to their explanation.
Hello Antonio
The user guides and chapters are created as documents in ODT format that can be printed or have PDF versions. Both versions are then placed onto the LibreOffice website for an LO user to download.
Placing a figure immediately above or below its cross reference will produce blank areas in the pages of a user guide. Using the top or bottom of a page for figure positions is a standard format used for user guides and manuals. This style is generally used when user guides are large and LO user guides do have over 300 pages on average.
I have been using this method of figure placement for a very long time when I started to layout pages manually ready for printing and before electronic publishing became available.
The method of figure positioning immediately before or after its cross reference is applicable only if an HTML version of a user guide is going to be created. A HTML version is normally only viewed on line using a web browser and not printed, therefore pages are not required.
To help solve the issue, I suggest that the above/below setting in cross references is applied to a figure cross reference after the figure number.
Regards
Peter Schofield
psauthor@gmail.com
Technical Writer, LO Documentation Team
The Layout of a user manual of software does not have to be like instructions for a microwave, where there are a couple of images (generally on the first pages) with a numbering of the buttons and which are consulted in the cooking instructions.
This type of manual is useful by keeping the first page marked or held with a finger while reading the content of the manual and quickly consulting the image.
In a user manual, of what concerns us (a program), the images must be as close as possible to the instructions for use so that the user, when seeing an image, can say:
"This is what I want to do" and go a couple of paragraphs or at most a page up or down to start reading the instructions regarding the operation, – without other images mixed in to interrupt their attention --.
- This applies to printed books, HTML, PDF or any other format in which the user manual has a continuity.
To avoid blank areas on the pages, you have to carefully choose the images, cut out unnecessary areas and adjust their size or location if necessary. This is meticulous work but it is always possible.
-
It is not advisable to prioritize the smallest number of pages over understandable content, with a logical and structured order.
-
If the intention is to save paper, you should also consider eliminating the blank odd pages that are generated when a chapter ends on an even page so that the next chapter begins on an even page.
Hello Antonio
I know how to adjust image size and place images on a page so that it looks good. I also know how to layout a page with headings, paragraphs and lists so that the text is easily understood.
Some users when they look at a user guide can get confused if there interruptions in the text flow. They also get confused when sentences and paragraphs are too long. If a user does use English as a mother tongue, they can also get confused with possessive apostrophes and word contractions.
I am not going to change my method of creating chapters and user guides.
The templates are used to make sure that format is relatively standard when created by several different users. Your new template is a good basis to start to upgrade the template instructions, which I am about to start.
Regards
Peter Schofield
psauthor@gmail.com
Technical Writer, LO Documentation Team
Just for the record, I agree with almost everything @bantoniof has said in this thread about figure placement and other layout issues, and I disagree with much of what @peewee does in his books. However, I am not going to argue about it.
Regards, Jean
I correct myself:
The Chapter Number and Chapter Title fields should not be used in the document title.
If you break the links to the linked documents, the text of the chapter title is lost.
It is only recommended if you work only with the Master document and you do not break the Links or
use it in isolated documents.
Hello Everybody
I have found the following errors in the new LO template LO_UG_Chapters_2Xx_EN when using it to update Impress Guide chapters to LO24.8. They are as follows:
Copyright page
The heading style used for the different sections is Heading 4 paragraph style. In previous editions and templates the heading paragraph style has been Heading 2. The headings on the Copyright page have been changed to Heading 2. Heading 4 style is not normally used in an LO user guide chapter. Only Heading 1, Heading 2, and Heading 3 paragraph styles are used in an LO user guide chapter.
Table of Contents
The Body Text paragraph at the end of a ToC is not a page break as in previous versions of ToC’s. This Body Text paragraph has been changed to a page break after and now uses a Page Break paragraph style. A Page Break paragraph style was available in previous versions of the template.
All Heading paragraph styles
The option in Spacing “Do not add space between paragraphs of the same style” has been selected. This option has now been de-selected because Heading styles require spacing between paragraphs.
List 1, 2, 3 and Numbered 1, 2, 3 paragraph styles
The option in Spacing “Do not add space between paragraphs of the same style” has been selected. This option has now been de-selected because the items in a List or Numbered style require spacing between paragraphs. This will make an Unordered or Ordered list easier to read and follow.
List paragraph style
The indent for items using List style is the same as the List 1 paragraph. Also, the option in Spacing “Do not add space between paragraphs of the same style” has to be selected to create a simple list with no bullet points. The items in a List should only consist of a single so that it looks like a shopping list, for example. There are examples of List style in use in the Impress and Draw guides.
Regards
Peter Schofield
psauthor@gmail.com
Technical Writer, LO Documentation Team
First of all a piece of advice:
If what you plan to post is a topic that has nothing to do with another topic already created or that covers other issues, the normal thing is to create a new topic with an appropriate title.
In this way the topics are not mixed as happens here:
General template issues are raised in this topic that seems more specific to Draw.
I don’t know what you are doing or intend to do with the template.
The template provided with SanityCheck is carefully designed to:
- Include the new styles (renamed “Text body” to “Body text” by the LibreOffice design team).
- Establish a logical and efficient hierarchy of styles.
- Avoid defining properties that must be inherited in the styles, so that changing a property in a parent style will propagate it to all children. (for example, changing the font color of the parent Heading style will change all Headings)
- Make the styles compatible for exporting chapters to HTML.
- Include the changes strictly necessary for maximum compatibility with documents already created.
The effectiveness of the template is demonstrated when applying it to old documents, when the changes in the document are minimal and in some cases imperceptible.
Several of the “alleged errors” you point out have been discussed in the post
Now my answers
The Heading 4 style is rarely used in earlier chapters, I have used it for the Copyright page titles to avoid index entries that point to the same page and it is how I use it in the Spanish documentation.
- Since the Copyright page for previous chapters is still maintained, you shouldn’t have to worry about anyone changing the format of this page.
The Page Break style (last paragraph style at end of TOC) has been removed in favor of the more convenient option of using the Heading 1 First style which adds the automatic (and necessary) page break after the TOC.
- This was discussed in the aforementioned post and implemented at the suggestion of @jeanweber
The “Do not add space between paragraphs of the same style” option prevents the space between those two lines from being added using the Heading style when a Heading has two lines. — this is a case that does not actualy appear in the guides, but could be occur.
You are confusing this option.
- This option does not remove the space between the Heading paragraph style and the following non-Heading paragraph style.
In the LO_UG_Chapters_2Xx_EN, the option “Do not add space between paragraphs of the same style”is not selected in any of the styles you indicate
- I don’t know which template you are looking at
The List paragraph style is the parent style that formats List 1, 2, 3 and Numbering 1, 2, 3 and by inheritance these styles do not have the option “Do not add space between paragraphs of the same style” checked.
If you change this style, the children of this parent style are affected (all list, ordered, and unordered list styles)
-
The List paragraph style is a parent style that formats all numbered and unnumbered list styles.
-
For a simple list, you should use the List contents paragraph style (included in Writer) and should be applied in the same way that the Table contents style is applied to tables.
This style, like other parent styles, should not be used in documents.