By David Coverston
Director-at-Large
Recognitions Chair
Membership Chair
Orlando Central Florida Chapter STC
membership@stc-orlando.org
If you are a technical communicator who writes software documentation, there is a good chance that you will need to include samples of programming code in your documents. Since you want to give your reader a visual cue that your text is code, you want to format it to look like code looks like in a code editor.
For your samples, you will want to use a non-proportional font. Courier New is one of the most commonly used non-proportional fonts, and it is a good choice even though one of my co-workers hates it. Other fonts you may want to try are Courier, Lucida Console, and Lucida Sans Typewriter.
Look at how well your code font stands out from the base font of your document. Observe the differences between the letter “l”, the number “1”, and the capital I, seen in the Arial font as
l, 1, and I . Also check the zeros and capital o’s; 0 and O.
Indentation is used in code to show the logical progression of the program, and is usually accomplished by spaces. You will want to preserve the indentation so that your reader can more easily understand the code.
You will have to play a balancing game with the font size. You want the font large enough to be read with comfort, but small enough that you will not have excessive wrapping of your text. The amount of indentation will play into this game. A couple of ways you can cheat at this is to change the orientation to landscape, and/or use smaller margins. You can also put large code samples into separate files.
If you create a code style, it is easier to apply formatting consistently to your documents. Code in developer’s tools is color coded to help the developer write the code. That can be a nice touch for your documents, but when you copy and paste the text into your authoring tool, it often loses the coloring. I’m going to let you in a little secret of how to get color-coded text into your documents.
You will need the free text editor Notepad++, available at http://notepad-plus-plus.org/. Once you have it installed and started, here are the steps to format your code:
- Copy your code text from your source and paste it into Notepad++
- From the menu, select Language, then select the language your code is written in. Your code will now be color coded. The example below is a Word macro, which is written in Visual Basic, so I selected VB.
- From the menu, select Plugins > NppExport > Copy RTF to clipboard.
- Paste the text into your document.
- Apply the code font you have selected as your standard.
Developers reading your documentation will thank you.