Authoring Tech Notes Using Documentation Tools
| Setting Up Documentation Tools | Adding Search Index Information |
| Authoring | Leaving Four X's |
| Adding Cross-Links | Preview Button |
A tech note focuses on a particular piece of functionality and includes examples, tables with links and short descriptions of useful functions, and mathematical textbook-like information. Sections are provided to link to other related documents.
The material below assumes that you have already set up an appropriate paclet directory structure for saving and working with documentation using Documentation Tools. To learn more about creating paclets, consult the Creating Paclets tutorial.
Choose Palettes ▶ Documentation Tools from the Mathematica menu bar. A palette will appear on the right side of the screen. Select the T tab at the top of the palette for tech note authoring tools.
When authoring paclet documentation for the first time with Documentation Tools, the paclet location will need to be configured. Click Add Paclet ... near the palette's top and navigate to and choose the top directory of your paclet. This will activate the links in the authoring notebooks for testing purposes.
If you have not already created a paclet documentation directory structure, then when a new paclet is added, Documentation Tools will automatically create the directory Paclet Name > Documentation > Language and the directories Guides, ReferencePages and Tutorials inside the Language directory. Additionally, the Symbols directory will be created inside the ReferencePages directory. By default, Language will be the English name for your chosen Wolfram System language and will typically match $Language.
Clicking New Tech Note brings up a dialog requesting that the title of the new tech note be specified.
Once that is done, clicking OK will construct a new tech note with the title and metadata already filled in. In addition, the tech note will be saved in the project's tutorials directory.
Note: The authoring notebooks contain a series of placeholders that will not be included with the build unless you explicitly edit them. These placeholders will typically contain four X's.
Note: A sample tech note can be found by clicking ? near the top of the Documentation Tools palette.
Enter the functions into the table so that the function template is in the left column and a short description is in the right. Using the same procedure from Authoring Symbol Pages Using Documentation Tools, use Template Input to format the template and function inputs.
Here is a table before Template Input is used:
Here is what the table should look like after Template Input is used:
You can add more rows to the definition box by placing the cursor at the end of the row and clicking the Add Row button in the Definition Boxes section on the Documentation Tools palette.
Note: Include only a few examples on the most important concepts mentioned in the tech note. If a user has a specific question about a function, they can go to the corresponding symbol page.
Add more tables by placing the cell insertion bar at a location in the notebook and clicking either the 2 Column or the 3 Column button.
The Related Guides section is for links to guide pages and the Related Tech Notes section is for related tech notes.
Choose Links on the DocumentationTools palette and pick the type of link from the column. (Expand More Link Tools for more options.)
"Keyword" cells are what the Mathematica search index uses when cataloging the authoring notebooks and are not case sensitive.
Keywords are set up to return the page in the list of search results if a user were to search for that word in the Wolfram Documentation.
Whenever a cell is left with the content four X's, it will be omitted by the build process. Thus the author need not do anything with such cells. Rows in a table whose elements are all four X's will be omitted by the build process. In addition, tables whose elements are all four X's will likewise be omitted.
