Re: Overall style points

Kristen James Eberlein

Nina, many thanks for your work on the documentation. I found it very useful.

Just a few comments:

  • Consider adopting a style guide and sticking to it. There are several widely used in the industry, including Microsoft Manual of Style and IBM Style Guide. The latter is my personal favorite and what I most often recommend to clients.
  • Sentence-style headings are best. All usability studies (dating back to the 1950s) show that it is more readable than the alternatives. If the headings are not standing out from the text, that's a reason to adjust how the headings are styled, for example, font size or color or a bottom border.
  • PDF bookmarks would be wonderful and make the document much more usable, but I don't know if Google docs can accommodate that :(

I moved a group (DITA Users) from Yahoo! to last fall, and I am extremely happy with the platform. And BTW, lots of technical communicators in our group!


Kristen James Eberlein
Chair, OASIS DITA Technical Committee
OASIS Distinguished Contributor
Principal consultant, Eberlein Consulting LLC
+1 919 622-1501; kriseberlein (skype)

On 3/10/2020 7:09 PM, Nina E wrote:

Hi, all. I'm the writer working on the documentation. Thank you for the comments on the owner/moderator reference doc so far!

To address some of the points that Shal raised:

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

I used sentence case from force of habit because that was the standard in my last tech writing/editing job. :-) That said, because many headings contain proper nouns (names of web pages, menu items, fields, and so on), I think sentence case helps those proper nouns stand out in the headings. Also, numbering will help the headings stand out (see the next item).

2) How about section numbers?

I agree that heading numbers will help in the printed/PDF version. (I'm not convinced that heading numbers are terribly useful in online presentation, but we'll see how it goes.) I didn't include them initially because I'm writing the documentation in Google Docs (that's the approach Mark and I agreed on when I first contacted him), and Google Docs doesn't have a heading numbering feature built in. However, I recently found an add-on that does the trick, so I'll try that in the next draft.

4) PDF Bookmarks, please!

As I mentioned above, I'm currently using Google Docs, but I'm not very familiar with its export-to-PDF capabilities. Maybe there's an add-on that will add bookmarks to PDF files; I'll look around. (If anyone happens to know of such a Google Docs add-on, please let me know.)

5) For the PDF pay attention to page breaks.

For sure. I'm waiting until the final draft, so I don't have to redo too many. :-)

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

Good suggestion - I'll give it a try.

Thank you again!


P.S. For the record, I own/moderate a restricted Premium group for a chorus of which I'm a member, and I serve as secretary on its board. We transferred our group from Yahoo Groups to two years ago this February, and we couldn't be happier that we did so!

Join to automatically receive all group messages.