Beginning with version 7.2.5, FxFactory lets you generate documentation for FxPack plugins directly from its user interface:
FxFactory knows a lot about your product: its plug-ins, parameters, thumbnails, etc. It uses this information to generate a rich template for your product’s documentation, as a set of web pages.
What’s really going on here?
Tired of wasting countless hours setting up custom websites and manually reproducing the anatomy of a product in HTML, we decided that FxFactory was in a great position to become a static website generator. One that takes advantage of its immediate access to a product’s structure to help us create documentation faster.
Linking to the documentation generated by FxFactory is easy. Existing Banner parameters can be configured to open the plug-in’s help page in response to a click:
Automatically-generated content includes rich descriptions for many parameter types. Your job is to fill in more details on your product, plug-ins and parameters to give users a complete guide.
As described in the sections below, you enter additional information in the FxPack. We added text fields that support Markdown content to help you create rich, structured documentation, easily:
What about my website?
Once you have completed your product’s documentation, you can easily export a self-contained version to be posted online:
When hosting documentation on your own website you may want to provide an exit link, allowing users to navigate back to a page of your choice when they are done browsing documentation. Specify the address of this exit page when saving the website:
The link back to your website is accessible by clicking the Back button in the navigation bar. When browsing the main page of your product’s documentation, this Back button leads users back to your website.
When clicking the Back button on all other pages in the documentation, it will navigate to the previous page, just as if you had clicked the browser’s built-in Back button.
Leave the Exit to website field empty when exporting if you do not wish to add a Back button to the navigation bar on the main landing page. (A Back button will still be present on all other pages, with the behavior described above.)
When can I start using this?
You can start using this feature now, but all products whose banners link to automatic documentation will require FxFactory 7.2.5 or later.
You can also create documentation now, export it for the web and publish it online. As a standalone website, there are no dependencies to consider.
Examples
The new documentation features in FxFactory are so flexible that we used them to generate this very website, using custom help sections:
If you are curious to see how the documentation for an actual product looks like, check out Caption Burner:
If you are interested in a product that contains more than one plug-in, look at Wipology (this is a work in progress):
The website produced by FxFactory is responsive (for desktop and mobile browsing experiences) and supports dark mode. As we improve the quality of our content generation, your products can benefit from our improvements simply by saving the product and/or exporting documentation for the web again.
Plug-ins
Each plug-in in your product gets its own page in the website generated by FxFactory. This page begins with the plug-in’s name and description. Below, FxFactory inserts a Compatibility section to list all host applications supported by the plug-in.
Add your own Markdown content to this section by entering it under the plug-in’s Info tab:
The above example provides a longer, in-depth description of the plug-in and adds a link to a separate section of the product’s documentation (Create your own Help Sections).
Parameters
Within each page created for a plug-in, FxFactory adds names and descriptions of all parameters. The automatic description varies from extremely simple (e.g. for Toggle Button parameters), to very rich (e.g. Object Tracker and Captions parameters).
Enter your own Markdown content under the parameter’s Help section:
Your own content appears immediately below the automatically-generated description. Explain how the parameter affects the plug-in’s output, rather than telling them what it is. Your own contributions are vital to making the documentation useful to our users.
The Include this parameter option lets you decide whether FxFactory will generate any documentation at all for the selected parameter. You may choose to omit certain parameters from the user guide, e.g. if they are always hidden by design.
The Include automatic content option lets you decide whether FxFactory will insert its own, automatically generated description for the parameter before your own content. You may want to omit the automatic content if the default description generated by FxFactory is insufficient. When this option is off, only your own Markdown content will be displayed.
Parameters → Popup Menus
Popup menus present users with multiple choices. While you could describe each option separately in your own, custom Markdown content for the parameter, FxFactory provides a better method to document what each option means.
Select a popup menu item to enter Markdown content that explains that choice, below:
FxFactory uses this information when generating the automatic description for the popup menu. Notice how the final output includes your own descriptions under the title of each choice available under the popup menu:
Notice the additional paragraph of text below the list. That content was entered via the parameter’s Help section, described in the previous section. The example shows how to leverage both approaches to provide the best documentation for popup menu parameters: custom descriptions for each choice available under the popup menu, and a general description of what the parameter does.
Parameters → Asset Chooser
Asset Chooser parameters present a more versatile popup menu to the user, one that may include image previews.
Similarly to the UI available for basic popup menus, you can enter Markdown help content for each choice presented to the user:
This information is used by FxFactory when building automatic help content for the parameter as a whole. This allows you to document how each choice affects the output of the plug-in.
Parameters → File List
File List parameters present a series of customizable attributes to the user, in a separate window.
Attributes are just another form of effect parameters, even if they are customizable only through a separate window. Describe the function each attribute plays in the output of the plug-in through a new Help section:
FxFactory uses the Markdown content you provide for each attribute when generating automatic the description for the File List parameter as a whole.
Parameters → Banner
Make documentation accessible to your users by adding and/or customizing a Banner parameter. A new option lets you link a banner to the documentation page created by FxFactory for that plug-in:
Make sure the Add button to perform the same operation is also enabled for the banner, so that users can access the documentation through a more intuitive Help button.
Did you know?
When FxFactory encounters a banner that lets users access product documentation, it automatically displays an on-screen button in Final Cut Pro and Motion to make that same documentation accessible via the Canvas. This makes your product’s user guide easily accessible by users.