How to Use the Template Project

Tip: These instructions involve the template project stored in flare-template-project/Template. Use this template project for user guides and more complex documentation projects. For simpler projects, use the template project stored in flare-template-project/WhitepaperTemplate .

Features of the Template Project

The template project can be used to quickly create a new documentation project. It is generally configured to work out of the box with only a few small changes.

Project Component Template Default
Targets / Destinations

The template project can create output for HTML5, PDF, and Word. You can modify the template project can be used to create PDF review packages.

The HTML5 target does not require any changes. In the General section of the target settings, the Output File box is set to index.htm. This should not be changed.

Be careful when using the Word target for production content. Flare does not fully support building Microsoft Word output, so it does not typically meet standards for sharing documentation with customers or individuals outside the company.

TOCs The template project provides only the Master TOC. You may want to add a Sandbox TOC for review packages.
Import Files

The import files in the template project are configured to import the required files from the global project.

By default, when you build any of the targets that come with the template project (HTML5 and PDF, for example), Flare imports the latest global files from the global project. At a certain point, you may want to modify the targets to disable the autosync feature. If you do so, you can use the !ImportFiles target to import the latest files from the global project without actually building any output.

When you use the !ImportFiles target, it appears to fail. This build failure is expected. The important aspect of this target is that the autosync feature is enabled and the latest global files are imported.

.gitignore The required .gitignore files are already in place throughout the folder structure, and should not be removed or altered. These files prevent unnecessary files from being added to the repository in source control.

To use the template project, complete the following steps:

  1. Copy the contents of the flare_template_project\Template folder to a new folder.
  2. In the new folder, rename the template.flprj project file.
  3. Open the project in Flare.
  4. Open the Project Organizer.
  5. Configure the following parameters:

    Folder File Parameter Required Configuration
    Destinations

    DocDemoSite destination

    Destination section > Directory box
    1. Change <template> to the lowercase name of the product (or some variation) you are creating a project for. For example, nessus, which results in docs/nessus. This will translate to a URL on the documentation demo web server. For example, http://docs.lab.tenablesecurity.com/nessus.
    2. Save the changes to the DocDemoSite destination.

    Note: It is not necessary to update the View URL box, as the feature does not appear to work.

    Destinations DocDemoSitePDF destination Destination section > Directory box
    1. Change <template> to correspond to the directory name you used in the DocDemoSite destination. This translates to a URL on the documentation demo web server. For example, http://docs.lab.tenablesecurity.com/nessus/Content/PDF/Nessus_UserGuide.pdf.
    2. Save the changes to the DocDemoSitePDF destination.

     

    Variables Default variable set ProductName and ProductVersion
    1. Change the Definition of ProductName to the name of the product you are creating a project for.
    2. Change the Definition of ProductVersion to the version of the product you are creating a project for.

      Note: In the future, when your product has a new version, you should update ProductVersion with the latest version number.

    3. Save the changes to the Default variable set.
    Targets PDF target various
    1. General tab: In the Output File box, change Template_UserGuide to <ProductName>_UserGuide, where <ProductName> is the name of the product you are creating a project for, without spaces or symbols. For example, Nessus_UserGuide.
    2. PDF Options tab: In the Document Properties section, in the Title box, change Template User Guide to <ProductName> User Guide, where <Product Name> is the name of the product you are creating a project for. For example, Nessus User Guide.
    3. Save the changes to the PDF target.
    Targets HTML target --
    1. Right-click on the HTML5 target.
    2. Click Make Primary.
  6. Open the Content Explorer.
  7. In the PDF folder, rename Template_UserGuide.pdf to the same name you used for the Title in the PDF target.

    Caution: Do not remove the .pdf extension.

  8. Build the !ImportFiles target to import the latest files from the global project.