Overall style points


 

Mark,

1) How about Title Case for section titles? I think that would help them stand out in the document body.

2) How about section numbers? In both the TOC and the body. Though they might be subject to change with each major revision I think they will help in citations to the manual. In the HTML version maybe supplement that with hover permalinks similar to those in the Help page - but keep them the same as the TOC links (if practical) and as short as practical, even when on a Header 2 or Header 3.

3) Will this be all one big HTML page? I'm a little ambivalent. That does enable browser-based search, but it seems like it could be a bit much. I think I'd prefer it broken into chapters (or smaller) with a dedicated search. Perhaps like a Wiki of its own, but with only Groups.io having edit permission.

4) PDF Bookmarks, please! I don't know what tool Nina is using, but hopefully its export to PDF function can be coerced to emit bookmarks. In MS Word that's in an option pop-up you open from the File dialog when you Export. In Acrobat Reader these Bookmars show up as a sidebar on the left with clickable links to go directly to headings.

5) For the PDF pay attention to page breaks. This goes beyond simple orphan/widow control in paragraphs (which seems to be mostly under control); there needs to be more use of Keep With Next (or whatever it is called in Nina's authoring tool) to avoid having headings orphaned at the bottom of a page; examples on pages: 12, 13, 15, 24, 26, 45, 52, and 73. Or widows at the top of a page; examples: 4, 7, 11, 12, 20, 54, 66, 69, and 71.

6) For the PDF consider using a new page for selected headings. All Heading 1 likely, and maybe all of Heading 2 as well.

Shal

Join docs@beta.groups.io to automatically receive all group messages.