This Week I Learned - 2016 Week 18

Write-up for last week or you might want to read the whole series.

Idea Debt. (HN thread) Break from your vicious cycle, do something, everyday, no matter how small is it. Build a habit.

One thing that really bother me when using LibreOffice is stability. The application tends to crash especially when editing large document. One of the way I resolve this is to break down the document into chapters or sections and then concatenate all the ODT files into one final file. The 'ooo_cat' program in OOoPy utility really helps. However, there are some quirks with the program, file merging still have some formatting issues and you have to manually adjust them.

Some may ask, why not using Markdown through Pandoc for writing? I've mentioned this last week, table creation using Markdown is still a lot to be desired. Furthermore, the document is a collaboration works with non-technical people, who only comfortable using MS Office. I can't blame them, in term of user experience, LibreOffice is still way, way behind.

DOE-STD-1029-92. Writer's Guide to Technical Procedures. Interesting document found while looking for guidance of how to write technical document. Context-wise, the target reader are those working under difficult and stressful condition, hence, the writing should be direct and specific to remove any ambiguous words which is subject to reader interpretation. Similarly, the recommendations in the standard can be applied to your own writing and coding as well. This is very useful if you want to write test cases as well.

Some good examples from the document are:

Avoid ambiguous words.
No: "the right valve"
Yes: "the right-hand valve" 

Avoid vague adjectives (words modifying nouns) and adverbs (words modifying verbs). Be specific, do not let user interpret.
No: "Drain the tank slowly."
Yes: "Drain the tank at 10 gallons/minute" 

Use spelled-out numbers, emphasis when needed.
No: "Energize 1 4.16 kV bus."
Yes: "Energize one 4.16 kV bus."

No: "Use 1 of the following."
Yes: "Use one of the following." 

No: "if the temp is 80EF ± 5EF..."
Yes: "if the temp is 75E to 85E F..."
Yes: "if the temp is 80E F (acceptable range of 75E to 85E)"

No comments:

Post a Comment