Formatting for Documentation

[SueBK]

I'm writing a user guide type document to go with the dataset and reports I've created in Excel. The writing of the guide is not an issue. But I'm wondering about people's preferred formatting conventions in manuals. It's quite a difficult topic to Google; to find the right words to find the right sites. So, I thought I'd just ask.

For example, how to do you choose to format the following so readers/users can 'see' them and separate them from all the rest of the text:
- file paths
- workbook names
- tab/worksheet names
- command button names
- macro names

Do you use different colours? Bold? Italics? A different font?

 

[ParamRay]

.
.

I think a lot of books use a fixed-width font, such as Courier New or Consolas...

 

[Macropod]

I think a lot of books use a fixed-width font, such as Courier New or Consolas...

Obviously an answer written by someone who doesn't read much...

SueBK: I suggest you look at what other forms of documentation are used in your organisation and ask the owners of the systems concerned for their preferences. Programmers will have one set of requirements; users an entirely different set of requirements. If it's for publication, you'll need to ask the publisher.

 

[SueBK]

I am 'the' programmer. (How that's happened, I'm still trying to figure out.) It's in-house documentation, there are no formats for software documentation, because they're town planners, not software developers. I like to make my documentation as simple to follow as possible and aimed at, well, complete nobs.

I've written a fair bit of documentation for Access databases, but never for Excel. I found I had quotes several times in most sentences, because workbooks, worksheets and my reports particularly often have multiple words in the title; macros not so much. It may not be conventional but I've gone with:

This is a workbook or file name
ws:this is a worksheet
This Is A Field (Heading)
"This is a field's content"
ThisIsAMacro
This is a button (used the same font as used on the buttons themselves)

So, it look something like:

Open this file, go to ws:blah de blah, click button A. The fancymacro will go to My Heading and filter on "active".

 

[Macropod]

Ordinarily, one would not apply different formats to content within a paragraph; the only exceptions might be cross-references, which would usually all be formatted in the same way, and hyperlinks, which would be formatted as such (though for printed documents, you wouldn't even do that). Applying different formats to content within a paragraph is distracting and detracts from the document's readability when overused.

Headings normally would be formatted using Word's Heading Styles (which can be modified, if appropriate) and facilitates the creation of a Table of Contents. For macros, you might use a specific paragraph Style that makes them stand out from the rest of the text - just don't expect the kind of keyword colouring you get in a VBA IDE, for example. For dialogue boxes and the like, you may need to include screen shots.

 

[SueBK]

As an editor (rather than a programmer) I understand about readability of text. As a user I also understand how confusing text can be if elements are differentiated. For example: if I have a report that I issue that is called "Daily Report" and I have a worksheet call "Daily Reporting", and the macro that runs off the "Daily Reporting" worksheet to create the "Daily Report" report is called Rpt_Daily, sitting behind a button that has the text on it "Daily Report" - some of my sentences can get pretty darn confusing.

Image all of that sentence without quote marks! By changing the style of the text the beginning and end of a title is clear. In my first draft everything (workbooks, worksheets, reports, buttons, macros, field names, field contents) were all enclosed in quotes, which was almost worse than no quotes. By using a different style of text for each different element the readability actually improves because the reader instantly knows "Oh, this is a macro" "This is a report" etc.

As an editor, having edited other people's manuals, I am well aware that programming boffins often do not think about how a user reads their documentation, but I was wondering if there were any general standards.