Each VIVO document consists of a large number of wiki pages. These pages must work well together, both on the wiki and when exported to a PDF file. Here are some suggestions to help that happen.

Page sizes

Keep each page to a manageable size, and focused on a particular topic. If you find that the page is too complex or too diverse, break it into smaller pages. Within each group of pages, the parent should contain introductory material or an overview, while the child pages explore individual topics.

Start with a Table of Contents

Start the page with a call to the "Table of Contents" macro. The Table of Contents will include all of the headings in the current page. It will also include a top-level heading for each child page, thanks to the "Children Display" macro.

When the document is exported to a PDF file, the "Table of Contents" macros are not included. Instead, the file begins with a table of contents for the full document.

Use all heading levels

The major headings on all pages should be Heading 1.  The second headings on all pages should be Heading 2.  Use the Heading styles only – do not format headings using bold, italics, etc.  When the pages are combined into a PDF file, the heading levels will be displayed properly and numbered correctly in the table of contents and in the document.

Pagination in the PDF document is controlled by the PDF template, not by the author.  Use page titles and page headings consistently.  The resulting PDF document will then be consistent.

Headings within the child pages are demoted accordingly, to keep the organization intact. So a level 2 heading in the Table of Contents might represent:

• a level 2 heading in the parent page,
• a level 1 heading in a child page,
• the title of a grandchild page.

Code

Use a code block macro to represent code.  A title for the code block is optional.

Use monospace in sentences to represent code.

Linking within the document

Links in the technical documentation wiki need to be checked to make sure they are referring to other parts of the tech doc, or external sources.  Links to pages in the project wiki are “okay” but need to be done carefully -- such links are often red flags that the tech doc is drifting into content better suited for the project wiki.  Links to the archive should be avoided.  Content from the archive that is relevant for the current version should be copied into the documentation wiki.

End with a Children Display macro

The documentation wiki for VIVO includes a child display at the end of every page.  There is no need to include a children display macro explicitly.  It will be added for you.