Adding Collateral Help FIles

    From The Document Foundation Wiki
    Other languages:

    What is a Collateral File?

    Collateral files

    The new Help system of LibreOffice enabled the already existing <object> element that allows to add objects into HTML help pages. Objects can be embedded or external videos, audio, and also files with specific MIME types.

    Starting from LibreOffice 6.1, the help system has had support for collateral files to help the user in understanding the textual description of the current page.

    What the collateral files are NOT

    The collateral files are not intended to replace or make obsolete the textual description of a feature. For example, a supporting file on Calc's trigonometric functions will not replace the help page on trigonometric functions. Nor will a collateral file on Pivot tables.

    The collateral file should not be used as an alternative to an encyclopedic text on a feature. There is no point to use a calculus textbook to explain the COS trigonometric function. The Help system expects the user to source their knowledge in appropriate textbooks and supplies simple examples acting as quick reminders or showing working function syntax.

    How do I submit a new collateral file to LibreOffice Help?

    Your help is welcome, of course.

    If you want to supply a new collateral help file to a specific help page, please open a ticket in our Bugzilla system and attach your file.

    Here is the process:

    1. Make sure you have all the credentials to open a bug in our bugzilla. If not, please follow the instructions in this wiki page.
    2. Open a new bug with the following settings:
      Component: Documentation
      Version: unspecified
      Summary: Enter a summary. For example, [COLLATERAL_FILES] File for help page on feature XYZ
      Description: describe the purpose of the collateral file and give as much details as you can. If you know the help page where the file belongs, then it is even better. You can supply the help page by indicating the link of the page in the help online. For example, https://help.libreoffice.org/latest/en-US/text/scalc/01/04060101.html
    3. Attachments: Attach your file to the Bugzilla report
    4. IMPORTANT: enter 117613 to the Blocks: field (this will link your contribution to the metabug).
    5. Submit your bug report.

    That's all.

    Note pin.svg

    Note:
    Collateral files are not available in the offline help package.

    Rules for Collateral File Creation

    "KISS" : Keep It Simple, Stupid.

    Well, sort of.

    The Help system must help the user. Sounds obvious but there is no point in inserting a complicated collateral file when the intention is to explain simple concept. For example, a Chart collateral file must not have a data series with hundreds of data points, nor must it display fancy coloring of the chart elements.

    Try to create a file with a minimal amount of text inside. Sometimes it is not possible, but some tricks will reduce the workload for translation:

    1. Keep the file small
    2. Unless otherwise justified, always provide Open Document Formats (ISO-IEC 26300), such as *.odt, *.ods, *.odp, *.odg, *.odf, *.odb.
    3. In Calc functions, you can use the =FORMULA(<ref>) to get the localized name of the function.
    4. Also in Calc, if a function belongs to a category of functions, consider one single file with many examples (see 1 above). For example, database functions DSUM, DCOUNT, DMAX, etc... can belong to one collateral file only.
    5. Do not create files with macros. Even with safe macros, the security warnings can bring troubles to the user.
    6. Do not use complicated styling, unless absolutely necessary
    7. Avoid files with external references, external links (they may create issues with corporate firewalls, etc.)
    8. There is no point in providing many files on the same subject. Improve the existing one.

    Subjects for adding collateral files

    Calc

    • Database functions DSUM, DMAX, DCOUNT, etc. The help pages already have a textual example that can used in a collateral file.
    • Statistical functions (provide a small but significant data sample with usage of statistical functions)
    • Financial functions
    • Goal seek
    • Solver
    • Multiple operations
    • Scenarios

    Writer

    • Indexes
    • Table of contents
    • Using page styles (landscape/portrait)
    • Styles

    Impress

    • Slide transitions
    • Object animations

    Draw

    • Layers
    • Objects
    • Dimension lines
    • Lighting objects
    • Distribution

    Base

    • Sample database

    Math

    • Sample equations

    Translation

    Some countries require the supply of help text and components of the software to be in one or more of the official languages. This requires the translation of the collateral file, when it applies.

    The default and fall-back language is en-US.

    Note pin.svg

    Note:
    The source files are located in the tickets listed below.

    Calc

    • file imtrigon.ods for complex trigonometric functions: tdf#117579
    • file trigon.ods for trigonometric functions: tdf#117592
    • file pivot.ods pivot tables and charts: tdf#117593

    Writer

    Impress

    Draw

    Base

    Math

    Uploading files to master branch

    Uploading of files will be carried out through gerrit.