Guidelines for technical writing, user manuals, etc.?

[Dougmeister]

Can anyone point me to a good guide on revising/writing technical user manuals?

I'm trying to decide when to use quotation marks, bold font, and italics. Also trying to use a different font (such as Courier New) for path and filenames.

E.g.:

Right-click the icon then select "Properties"
Right-click the icon then select Properties

In the "Target" field, append the command-line option "/s"
In the "Target" field, append the command-line option "/s"

Click "Start", "Run", then type C: \runme.bat

 

[johnny.dacu]

There is some info: http://www.io.com/~hcexres/textbook/instrux.html. Maybe it helps

 

[Cogman]

Well, for starters, I would suggest using something along the lines of latex -> http://www.latex-project.org/

That way, you can create different properties or functions for your document (so if you decide it should be bold, you only have to change one line of the document code.)

After that, when giving specific instructions, the style to highlight specific user actions is left up to the document writer. Consistency is more important then style in most cases (so long as you aren't using wingdings). Writing, even technical writing, is more of an art then an exact science (despite what your english teacher might have said).

In other words, all the options you have presented are correct. I would, however, suggest that you don't change fonts mid-document. It is distracting.

 

[CycloWizard]

I agree with Cogman - the bottom line is that it needs to be consistent throughout the manual. As long as you pick a format and stick with it, it shouldn't make a big difference what it is.

I'm in the process of writing a lab manual for a course I'm teaching this fall, and a large part of that manual is dedicated to detailing how to write a technical report... I'm using LaTeX to write mine, but there's no reason any word processing program could not be used. Google Docs is now set up to work with LaTeX (http://docs.latexlab.org/), which gives you an easy starting point if you're not familiar with TeX. For the specific cases you mentioned, they would be easily written as follows:

Right-click the icon then select "Properties"
Right-click the icon then select \textbf{Properties}

In the "Target" field, append the command-line option "/s"
In the "\textbf{Target}" field, append the command-line option "\textbf{/s}"

Click "Start", "Run", then type {\tt C: \runme.bat}

\textbf{} makes the enclosed text bold, whereas \emph{} italicizes. The \tt command uses a Courier-like font for the enclosed text (can't recall exactly which it uses)

 

[AtlantaBob]

I agree with Cogman - the bottom line is that it needs to be consistent throughout the manual. As long as you pick a format and stick with it, it shouldn't make a big difference what it is.

I'm in the process of writing a lab manual for a course I'm teaching this fall, and a large part of that manual is dedicated to detailing how to write a technical report... I'm using LaTeX to write mine, but there's no reason any word processing program could not be used. Google Docs is now set up to work with LaTeX (http://docs.latexlab.org/), which gives you an easy starting point if you're not familiar with TeX. For the specific cases you mentioned, they would be easily written as follows:

Right-click the icon then select "Properties"
Right-click the icon then select \textbf{Properties}

In the "Target" field, append the command-line option "/s"
In the "\textbf{Target}" field, append the command-line option "\textbf{/s}"

Click "Start", "Run", then type {\tt C: \runme.bat}

\textbf{} makes the enclosed text bold, whereas \emph{} italicizes. The \tt command uses a Courier-like font for the enclosed text (can't recall exactly which it uses)

I agree with Cogman and CycloWizzard..... LaTeX is great for this - if you manual will eventually be produced with something LaTeX compatible (i.e., anything that can be read as a PDF). I used it for my master's thesis in a similar situation, and it was great. Compared to it, Microsoft Word styles are, in my opinion, a pain in the rear....

 

[Dougmeister]

Great info. Thanks!