Use Case: i-net software documentation

These are some of the scenarios that we use i-net Doqua in.

This part of the documentation is build using DokuWiki and the Site Export plugin. So the basic style set is good. But there are sometimes flaws like empty text blocks, duplicate white spaces and so forth that the wiki cannot handle correctly. The following rule set helps us for some other problems as well:

• all documents have to be HTML DTD compliant (via TidyValidateHTML trigger)
• all links throughout the documentation have to be valid and existing (via TidyLinkChecker trigger)
• all documents consist of a header and a footer that is fixed throughout the documentation
  • some more elements are fixed, like stylesheet, metadata and so on.
• all documents need a breadcrumb bar that shows the current page and the path to get there

Finally we have our test system (a Jenkins/Hudson server) run these test when the product is being created. (several times a day). So we can closely monitor changes in the documents and upgrade them as needed.

The most rules are the same here but there are some distinct differences to the i-net Clear Reports Documentation.

The i-net Designer documentation is completely custom made, meaning the HTML is hand-written. Especially the formulas section is very extensive and grew along the product.

Over the time several users wrote sections of this documentation differently: some gave examples, some simply wrote down the syntax, some had a lot of text, some wrote the docs using a simple text editor and other ones used Microsofts Frontpage.

To come by these different styles we added the following set of rules:

• there can be additional “see also” elements which, if present, have have a fixed structure
• all formula documents have to have a language description image in the header
• formulas have to have an example, parameter, usage and return value description