Creating documentation navigation

This is a multi-step process that will step you through creating a category, creating articles, creating a navigation file, and then connecting it all together to appear as a table of contents to the documentation articles.

The Product Documentation tab is special

The Product Documentation tab is special because it offers some features that other areas of the wiki do not.

• You can include multiple sets of documentation, each with its own accordion tray and navigation in the left column.
• You can create a custom navigation that lets you control the order and hierarchy of the articles in your documentation set.
• You can include multiple product releases in one accordion tray, where the user can select which release to view from a drop-down. This is only present when you have more than one entry with the same product name but a different release name.
• You automatically get the toggle links that take you between Current editable edition (latest version of the article) and Original noneditable edition (version 1 of the article).
• These toggle links are only available on articles with Content Type set to Product Documentation.
• Clicking Original noneditable edition puts you in mode=original and all links you click within Product Documentation stay on mode=original until you toggle back to Current editable edition.
• The purpose of these links are to help users quickly jump back to the original set of documentation that was published.

Create a category for the documentation

Create a specific category for the version you are publishing product documentation for. Follow these steps to create the category:

1. Go to the Notes client.
2. Go to Advanced > Content Categories.
3. Click the Create Category button.
4. Enter information in the following fields on the Content Category tab.
• Category Name: Enter a category name for your documentation. For example: My Company Software Version 2.0 documentation.
• Include in Category Archive List? Select so that the category will appear in the wiki category list on the home page.
• Content Type: Select Product Documentation
• The Attachment URL and JSON File fields can be left blank for now. You will populate them later.
5. Enter information on the Formatting tab. You can even just type "Coming soon" because you can come back later and update the text.
6. Save & Close the category.

Create articles you want in the documentation

Create articles to include in your documentation. If you do not have all the content yet, create stub articles with titles as close to what they will be as you can. You can create more articles later and update the navigation file but create some articles to start with.

At minimum, when creating articles you need to make these selections:

1. Enter a title for the article. The title will be used in the navigation file so if you are creating stub articles, make sure you enter titles that are close to what you want.
2. Select the category you created above. Many people also select the Product Documentation category as well.
3. Select Product Documentation for Content Type.

Note: If you forget to set the Content Type, see Troubleshooting below for details on an agent you can use to set Content Type on all selected articles.

Run agent to set product name and release on articles

Next, associate the articles with a specific product and release. Follow these steps:

1. In the Notes client, go to the Recently added by category view.
2. Find and expand the category you created to see all the articles you created.
3. Select all the articles in the category.
4. Go to Actions > Change article product or release name
5. Enter a product name and release and click OK to update all selected articles.
• Write down what values you entered because you will need them later.
• The product name will not appear in the user interface.
• The release name will appear in the user interface.

Create and attach a JSON navigation file

Create a JSON file

Create a JSON (JavaScript Object Notation) navigation file to arrange the order and hierarchy of the articles.

Here is a sample JSON file: Download this JSON navigation file to use as a starting point.

a. The JSON file should begin and end like this. You will put your article entries in the middle.



b. A first level article will be listed like this:


In the first entry, line 2:

• name:'Introduction' is the title that appears on the article.
• type:'first' is the first level in the navigation hierarchy.
• link:'Introduction' is the name of the article in the URL.

In the second entry, line 3:

• You can see that the name and link do not match. That is because the title that appears in this article was changed after the article was created. The link value needs to match the name of the article that shows in the article URL.

c. When a first level article has children this is what it looks like:


The entry on line 4 is a first level entry that includes a new parameter called children and it references the name of each child entry (not the link of each child).
Lines 5, 6, and 7 are children that have type:'second'

This same method can be used down to third, fourth, and fifth levels.

d. The last entry in the JSON file, line 9, does not need a comma at the end of the line.
All the previous entries do need a comma after each line. This is a common troubleshooting issue. Always make sure each entry in the JSON file ends in a comma except the last entry.


e. Save the JSON file and name it using this convention: filename_json.jsn

Here is a sample JSON file: Download this JSON navigation file to use as a starting point.

Note: Duplicate article names are not supported.

Attach a JSON file

Follow these steps to attach the JSON file to the category page:

1. In the Notes client, edit the category page.
2. Attach the JSON file and save the category page.

Configure the wiki to find the JSON file

1. In the Notes client, go to Advanced and select Custom Content.
2. Select the Product documentation tab.
3. Go into Edit mode.
4. In the Navigation field, enter a new line that includes parameters based on things you have done up to this point.. The Navigation field contains one line for each navigation file you want to include. Here is the line you must enter:
   
   

   Tray Label | Product name | Release name | JSON Attachment URL | Name of category page JSON file is attached to

   
   Each line is made up of the following values:
• Tray label: Enter the name to appear in the accordion tray label in the user interface.
• Product name: Enter the same product name that you entered when you set the product name on articles in step 3.
• Release name: Enter the same release that you entered when you set the release name on articles in step 3.
• Link to JSON navigation: This can be found by opening the category you attached the JSON file to, highlighting and copying the Attachment URL, and pasting it here.
• Category name: Enter the exact category name the articles are associated with.
5. Save the Custom Content form.

Syntax:


Here is an example:


Notes:

• This is split on multiple lines for display purposes only, your entry in Custon Content should be all on one line with no line breaks.
• If you must use the single-quote (') or pipe (|) character in the Label or Product name in a tray entry, use \' or ' for the single-quote and ' for the pipe.

Test the navigation

Once you have the navigation configured you will want to test it out. Follow these steps to test the navigation:

1. Open your wiki in a browser.
2. Click the category page link in the wiki category list on the home page.
3. The navigation should load on the left, in its own accordion tray, with a link to the category page at the top and the actually category page on the right.
4. Click links in the navigation to verify that the correct articles load and that the article names highlight.

Troubleshooting

Tray for your documentation is not showing in the navigation

• Make sure you have correctly entered a line for your documentation in Custom Content, as described above. This tells the wiki how to reference your documentation and in what order to show it in the accordion.

The tray for my navigation is there but there is no navigation

• Confirm that the category name you entered in Custom Content matches the actual category name. Look for spaces or other typos.
• Confirm that you have the correct link to the JSON file, which you can find on the category page.
• Make sure there are not duplicate article names in the JSON file.
• You can use debugging tools in your browser to track down why the JSON file does not load. Here is an example error message. See where it says "Value collided".
  

  [Widget dijit.Tree, dijit_Tree_2] _connects=[7] _deferredConnects=Object : error loading root children:
  

  Error: dojo.data.ItemFileReadStore: The json data as specified by:
  

  [/ldd/lotusimportwiki.nsf/0/3A8096A4C44B5EEF8525773F00624F4D/%24FILE/toplevelmap_json.jsn] is malformed.
  

  Items within the list have identifier: [name]. Value collided: [Preparing DB2 for i5/OS: wp7_hc]

Clicking a link in the navigation loads the wrong tray, or loads the top tray

This happens because the wiki does not know what navigation to associate the files with.

• Confirm that you ran the agent to set product name and release name on the articles.
• If you ran the agent, you can look for discrepancies by selecting an article, right-click, and view Document Properties. On the design tab (second tab), look at the values for the productName and releaseName fields and make sure these match what you entered as Product name and Release name in Custom Content.

Clicking an article takes me off of the Product documentation tab and there is no navigation

Make sure the content type of all the articles is set to Product documentation. If you find that content type is not set correctly, you can do one of the following things to set it:

• Go in to each article and change Content type to Product documentation.
• Run an agent to update Content type on all selected articles:
1. In the Notes client, go to the Recently added by category view.
2. Find and expand the category you created to see all the articles you created.
3. Select all the articles in the category.
4. Go to Actions > Change article content type
5. Select Product Documentation and click OK.

Searching for an article and clicking it loads the wrong tray, actually loads the top tray

This happens because the wiki does not know what navigation to associate the files with.

• Confirm that you ran the agent to set product name and release name on the articles.
• If you ran the agent, you can look for discrepancies by selecting an article, right-click, and view Document Properties. On the design tab (second tab), look at the values for the productName and releaseName fields and make sure these match what you entered as Product name and Release name in Custom Content.