Technical writing

Typography

The first thing that I should mention is that writing documents is typography. "Putting documents" together is typography because we are designing with text (Butterick, 2019). So, we should consider ourselves typographers since we are constantly designing documents.

I would suggest taking a look at "Butterick's Practical Typography" since it is a really good book about it and it reads smoothly. I will mention some important points here according to Butterick's "Typography in ten minutes":

1. The most important typographic selection is on the body text. This is due to the fact that it is most of the document.

2. Choose a point size between 10-12 points for printed documents and 15-25 pixels for digital documents.

3. Line spacing should be between 120-145 % of the point size.

4. Line length should be between 45-90 characters. This is roughly 2 or 3 small caps alphabets:

   abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcd

5. Mind the selection of your font. Try to avoid default fonts such as Arial, Calibri or Times New Roman.

Editors

Another point that I want to touch in this post is about editors. The first question that arises is "what editor should I use?". The short answer is: use whatever your peers are using. That's my best advice; that way you have people to discuss with you about your doubts.

The long answer … is that each editor has its weak and strong points. I have written scientific papers in LaTeX, LibreOffice Writer and MS Word; all of them look professional. So, in the end, you can write your documents in several ways and achieve a similar result. I prefer to use LaTeX for long documents since it is centered in the structure of the document instead of the appearance and this is the way one should manage a long document like a dissertation, in my opinion.

If you just want me to pick one editor and suggest it to you, I would say that you should ride with LibreOffice. A good reference for it is "Designing with LibreOffice". Once you learn how to use styles you will ask how have you been writing documents all this time.

There are two main flavors for editors that I am going to discuss: WYSIWYG (What You See Is What You Get) and markup-based editors.

• WYSIWYG. This category is the one that most people is familiar with. Two examples are:

  • LibreOffice writer; and

  • Microsoft Word.

• Markup-based editors rely on marks on the "text" to differentiate sections and styles. In this case, your text looks like code, as seen in the following image

  

  Some examples are:

  • LaTeX;

  • Markdown; and

  • reStructuredtext.

Independently of what your main editor is I suggest that you use Pandoc. It allows you to convert between several formats, making the process a little bit easier. There is even an editor based completely on it named Panwriter.

References

1. Matthew Butterick (2019). Butterick's Practical Typography. Second edition, Matthew Butterick.

2. Wikibooks contributors. (2020). LaTeX. Wikibooks, The Free Textbook Project.

3. Bruce Byfield (2016). Designing with LibreOffice. Friends of OpenDocument, Inc.

4. Deville, S. (2015). Writing academic papers in plain text with Markdown and Jupyter notebook. Sylvain Deville.

5. Eric Holscher (2016). An introduction to Sphinx and Read the Docs for Technical Writers.