Technical writing — Some suggestions

  • A few of this com­men­ts are mar­ked as [ENGLISH], [ITALIAN] becau­se they are spe­ci­fic to a par­ti­cu­lar lan­gua­ge. All the others are valid for both Italian and English.
  • When you defi­ne a new term for the fir­st time, use \emph{} (ita­lics). After that, do not use ita­lics any more.
  • [ITALIAN] Il plu­ra­le di una paro­la ingle­se usa­ta in una fra­se in ita­lia­no non vuo­le la s. 
    • Un data­ba­se può esse­re divi­so oriz­zon­tal­men­te in uno o più shard.” (non “shards”)
    • Pushare, deli­ve­ra­re, mer­gia­re, etc. dan­no ori­gi­ne ad una puni­zio­ne corporale
  • When you refer to chap­ters, sec­tions, etc., you need to men­tion what you are refer­ring to, not just wri­ting down a number. 
    • 6 con­clu­des the the­sis” -> “Chapter 6 con­clu­des the thesis”
    • The archi­tec­tu­re is sho­wn in 2.1” -> “The archi­tec­tu­re is sho­wn in Figure 2.1”
  • Use capi­tal let­ters when you refer to a spe­ci­fic chapter/section/figure/whatever, use non-capi­tal let­ter in other cases 
    • In Chapter 6”
    • In the next chapter”
  • Do not start a chap­ter with a sec­tion title; the­re should be some text bet­ween the two. This applies also to sec­tion and sub­sec­tions. For example:
    Chapter 1: A proof that P=NP
    1.1 Definitions
    1.1.1 Class P
    is wrong. You should wri­te for example:
    Chapter 1: A proof that P=NP
    The que­st of pro­ving that P=NP is over! In the next sec­tions, we pro­vi­de some defi­ni­tions and then…
    1.1 Definitions
    There are two main com­ple­xi­ty clas­ses invol­ved in this proof, P and NP
    1.1.1 Class P
  • [ENGLISH] Do not use col­lo­quial abbreviations: 
    • doe­sn’t” -> “does not”
    • can’t” -> “can­not”
    • let’s defi­ne” -> “let us define”
  • As a gene­ral rule, small num­bers, such as who­le num­bers smal­ler than ten, should be spel­led out. If you do not spell num­bers out it will look like you’re sen­ding an instant mes­sa­ge. But: if you are refer­ring to a con­stant in an algo­ri­thm, than it is ok to use the number: 
    • There are 3 options” -> “There are three options”
    • In the base case, the result is equal to 1”
  • If you are using latex, $this$ is not the right way to make the word “this” in ita­lics. $this$ means varia­ble t, h, i, s mul­ti­plied toge­ther, and latex use odd spa­cing bet­ween the let­ters becau­se of that. Use $\mathit{this}$ instead.
    If you are lazy, use $\This$ but define:
  • [ENGLISH] Whenever you com­bi­ne two words to make an adjec­ti­ve, you should use a dash bet­ween them. If the two words are not used as an adjec­ti­ve, the dash is not needed. 
    • A fault-tole­rant protocol
    • Fault tole­ran­ce is important
  • Do not use the futu­re ten­se to discuss about the fol­lo­wing chapters/sections/whatever: may­be when you wri­te, the next chap­ter has not been writ­ten yet, so it make sen­se to talk about it in the futu­re. But when the rea­der reads your the­sis, the chap­ter is alrea­dy the­re, so you should refer to it in pre­sent tense 
    • Chapter 5 will pro­vi­de the con­clu­sions” -> “Chapter 5 pro­vi­des the conclusions”
  • Very impor­tant: biblio­gra­phic refe­ren­ces are paren­the­tic, so they should not be used as part of the sen­ten­ce. They should just appear in their squa­re brac­ke­ts at the end. 
    • In [1] it is sho­wn that” -> Tizio et al. have sho­wn that.… [1]
    • [1] sug­gests that ” -> In 2008, Caio and Sempronio have sug­ge­sted that… [1]”
  • The idea is that you want to make the life of the rea­der sim­ple: if [1] is used as a sub­ject without any addi­tio­nal infor­ma­tion, the rea­der needs to inter­rupt the rea­ding, go to the biblio­gra­phy, figu­re out who is the author of [1], when the paper has been publi­shed, etc.
  • Latex-nazi:
    • blah blah \cite{citation}” -> “blah blah~\cite{citation}”
    • blah blah \ref{reference}” -> “blah blah~\ref{reference}”
  • Simplify, sim­pli­fy, sim­pli­fy: avoid com­plex sen­ten­ces, avoid secon­da­ry, ter­tia­ry etc sen­ten­ces. Do not think in Italian and trans­la­te in English — Italian is much more verbose.
  • Simplify more! Look at eve­ry sin­gle sen­ten­ce and think: is the­re a way to con­vey the same infor­ma­tion in less space? 
    • In the fol­lo­wing chap­ters the­re are going to be pre­sen­ted some methods…” -> “The fol­lo­wing chap­ters pre­sent some methods.…”
Scroll to top