Top Ten: Documentation Tips (from a technical point-of-view)

Quite a few of my master thesis students are currently writing up their reports. As a tribute (and help?) to them I want to list my top ten documentation tips. These tips are more from a technical point-of-view and not really from a language or grammar point-of-view. I am thinking of those ten items that annoys me most and how you can avoid them…
I am “grown up” with framemaker and now I use LaTeX and openoffice. Framemaker is a commercial tool, but it is very good from a documentation point of view, as you also learn how to properly type set your document. The tool can help you if you want to, but you can also override the settings according to your liking. LaTeX is less so. Now I use openoffice and the mere fact that it is free just makes me like it more and more for every day that passes on. It has most the features of Microsoft Word and has in some sense also cloned a couple too many… but that’s another story.

  • #10: Do not insert extra carriage return after paragraph

    I cannot find words that properly expresses my feeling for documents where extra carriage return is used to create extra space between the paragraphs… Brrrr. There are paragraph settings that can be changed such that this distance is set automatically. Surprisingly often you get this from someone who uses a commercial software and actually pays money to not use the features of the tool.
    Anyways, the general conclusion here is: use the template and the paragraph designer to set margins, spacing, etc.

  • #9: Do not number headings, captions, references manually, please!

    Once again, quite often you find manual numbering of headings, captions, references, etc., in documents from a tool that actually costs money. So let me get this right: one goes to the store and buys some software for $200 and then does not use it. Why? So, use that autonumbering and outline numbering functions (Tools > Outline numbering … in OOO). Use the running variables and use the cross-references (Ctrl+F2 in OOO).

  • #8: Use the Index, LOT, LOF, LOP, LOC to your advantage.

    Most documentation tools enable you to create lists of almost anything… list of headings (i.e., the index), list of figures (LOF), list of tables (LOT), and list of cross-references (LOC). See them as something useful!
    The TOC is excellent to use to check your outline.
    The LOF and LOT are good to have when you want to check consistency of your document. Are the captions similar? Are the captions well explained, e.g., you will be able to more quickly spot erronous captions like “A CMOS gate” instead of the more correct “A schematic view of a CMOS gate consisting of an NMOS and a PMOS transistor.”
    The LOC will help you to double check that you have cross referenced to all the figures/tables in your document. A figure/table should never be left unreferenced. You can generate a LOC and a LOT/LOF and then compare them. Are all the tables/figures in both lists?

  • #7: Use some kind of revision, history, document ID

    Scenario: “Hey Mr. Man, do you remember this document you wrote six months ago? You had a presentation and then you gave us some PDF hand-outs with equations that described how you calculated the SNR of a common-source stage. Could I get a copy of the master ODT?”
    Answer one: “Hmm, I don’t remember, let me search through all of my hard disk and e-mails and check for some random name, like maybe ‘document.odt’ or ‘handouts.odt'”
    Answer two: “Sure, I see from your print that it was document 0033, rev C. Here it is.”
    This is of course standard procedure in industry but in academics it is considered odd to even mention revision or mark the documents accordingly. I have actually got that kind of comments from people at the philosophy faculty. From them I got documents like: “rapport.docx” 😦

  • #6: Good looking pictures

    Presentation is important and then pictures have to be good looking. This means for example that the arrow head should not be as big as the box it is pointing to. All the arrow heads should be equally large unless they are used to indicate something special. The text of a box should be centered. The picture should fill its purpose, otherwise remove it.
    In short, the picture should not look like a pre-school sketch. Use a good tool (no, that’s not the built-in drawing function in e.g. Word, use Visio instead – or OOO draw for free).

  • #5: Use equations in text

    And please, please, please: do not use normal characters in running text when you want to display, write an equation. All equations or variables or so should be written with the same characters, i.e., insert them as an equation.
    Do not use “*”, “x”, nor “.” as multipliers.
    Do not use hand-written “…” as a multi-dot indicator.
    etc.

  • #4: Maintain and use a bibliography database

    Maintain a bibliography database, do not add them manually into the document. For LaTeX this is kind of natural with BiBTeX and with openoffice you can easily use another spread sheet as source for your references. The reference lists can then be created automatically for you.
    This is good for several reasons: (1) you and your team can build up that list together and use eachothers background research, (2) you can add comments in those spreadsheets to outline the reference: ”Good one! Guru reference.”, ”Not that good, immature publication.” and (3) more.

  • #3: Use file referencing for pictures/simulation results

    To save document size and to make the software a bit faster it is sometimes advantageous to use referenced pictures rather than pasting them into the document. You can have a subfolder, say figs in which you place all figures. In conjunction with this you have a MATLAB/Cadence setup that enables you to recreate all figures if you like/need to. For example, you need to resize all pictures to fit a presentation rather than a document. Or you need to make all lines in the plots thicker or of another color, etc. Then this can be done much more conveniently afterwards.
    A document deliverable could very well be a zip file as well as an odt (actually odt is a zipped xml file with a built-in ”directory structure”)

  • #2: Think porting

    Ok, today you probably want to port your document between different formats. Probably – in most cases – it is sufficient to think PDF, however there could be more to it, say all these:
    HTML – PDF – ODT – DOC – TEX – XML – XLS – PPT – ODP – ODG
    From the same master you might want to generate HTML for a world-wide presentation of your research/results, ODT as master document, DOC to those-other-people, TEX to a paper submission, XML/XLS for interaction with some database (say that you want to have a table in your document with fresh simulation results from Cadence), PPT/ODP/ODG for presentation and illustrations of your work.
    My suggestion for you is to put some effort in understanding where the hurdles are. How can you easily go from one to another and why cannot you? If you spend so much time on writing the report/paper, how come writing the PPT presentation also take time?

  • #1: See your document as a design

    In the same way you treat your schematic/circuit design or whatever, you should also treat your document. Or vice versa: if your document is sloppy, then probably your design is too. Please, think of this when you present your document.
    To this we could add other aspects such as scripting, programming, etc. Once you get this view of your document, you will also appreciate the stuff “behind” the actual document. You will be able to define structures, templates, referencing, directory structures to maximize your efficiency. You can automatically create presentations from reports and from say Cadence databases.

Any other ideas?

Advertisements

3 thoughts on “Top Ten: Documentation Tips (from a technical point-of-view)

  1. thank you for the advices, really useful. But I have hard time downloading Latex for windows. Would you know any website I could get it free?

  2. Thanks. Now, actually I am not a windows-guy, so I understand that you have a hard time 😉 No, but seriously, previously I used to work a lot with MiKTeX and was quite happy with that. It worked quite brilliantly and supported jumping back and forth between windows and unix (yes! unix).

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s