Ugur Akinci published a useful post earlier this week on The Discipline of Punctuation in Technical Writing. I agree with Ugur’s general point, that technical writing needs to display “discipline, precision, and consistency”, and with many of his specific statements, but there is one statement he makes that I think requires some clarification.
Technical writers need to be aware of what they are doing at all times, even when they are applying rules or guidelines to the material in front of them. Punctuation rules are no exception: if you think that applying a rule is going to make the material less useful to the audience, then follow your common sense and make your material useful first.
The example that came to my mind when I read Ugur’s blog post was the matter of quotation marks. Ugur writes:
If you are using quotation marks, periods and commas should be placed right inside the second quotation mark.
The first thing to say is that Ugur is citing the conventional rule for American English, while the conventional rule for British English is the opposite – punctuation marks are generally placed outside quotation marks. Your organisation must decide whether the British or the American convention is appropriate for your audience.
The second and more important point is this. In a lot of technical material, quotation marks are not really about quotations; that is, they are not about reported speech as a fiction writer or journalist would understand it at all. Quotation marks are frequently used to distinguish interface elements, menu commands, or used as part of code sample that needs to be explained. (My preference is to use bold type or italic type for interface elements and menu commands.)
Adding punctuation marks to code samples or to code elements included in the text in technical documents may cause serious problems, as the added punctuation may inadvertently make the code incorrect. Some programming languages use quotation marks, for example around parameters, and adding any additional punctuation marks inside these quotation marks would be quite wrong. It is possible to imagine a situation in which a code sample which included quotation marks was part of some running text. In this case the technical writer must think carefully, and understand that preserving the integrity of the code sample must take precedence over any other rule for placing punctuation near quotation marks. In many organisations this problem is avoided by setting code samples and code extracts in running text in a monospaced font such as Courier, so it is easy to see what is part of the code sample and what is not.
So please remember: when you are applying rules to your technical material, don’t forget to think about what you are doing.