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