4 ms·

A guide to technical report writing [pdf]

83 points by smartmic 3y ago

simonw 3y ago
The first tip I'd give is don't publish your technical report exclusively as a PDF, because those are bad for linking to, bad for searching, bad for copying-and-pasting out of, bad for reading on mobile phones, harder to crawl and index, and harder to update in the future. If you really must have a PDF at least make a proper web page version first and then link to the PDF as an alternative format for people who really, really want it. (This pet peeve aside, this is a good document with some excellent advice in it.) Another problem with PDFs: since they don't particularly encourage having a single, unambiguous URL you can end up with confusing multiple copies of them floating around. This post links to https://ias.ieee.org/wp-content/uploads/2023/06/2020-01-16_IET_Technical_Report_Writing_Guidelines.pdf https://ias.ieee.org/wp-content/uploads/2023/06/2020-01-16_I... - which has 2023 in the file path, 2020 in the filename and declares it to be copyright 2015 in the actual document. A search for "A guide to technical report writing iet" lead me instead to this document: https://www.theiet.org/media/5182/technical-report-writing.pdf https://www.theiet.org/media/5182/technical-report-writing.p... - same organization, similar content, different document design. Is this the updated version of that 2015 one? Hard to tell, because it doesn't have a date anywhere.
- scrlk 3y ago
  > Is this the updated version of that 2015 one? Correct - it uses the latest IET branding. The one linked in the submission uses the previous IET logo. PDF metadata also points to that document being created in 2020.
  - logicallee 3y ago
    >Correct - it uses the latest IET branding. it's really much more than that. They laid it out gorgeously, introduced pull quotes, and typeset things so the eye could visually follow the content much more easily, including through text in different colors, bold and various typesetting devices. They rearranged it a bit. They made it a breeze to read through. They also added a bunch of irrelevant stock pictures which have nothing to do with the text and contain no information but somehow still made it much easier to read through. Is the content the same or was some of it omitted? The original PDF had more pages and this one has a lot of photos taking up space, and seems to have more whitespace as well.
- EFreethought 3y ago
  That second one is a two-column PDF file. The only think I hate more than a PDF file on the web is a two-column PDF file. At least with one-column you can just scroll in one direction.
  - deleted 3y ago
    [deleted]
  - account-5 3y ago
    I don't know why you're being down voted. Two column articles, pdf or otherwise, are simply harder to reader and know your place. Should be banned. Unless of course I'm missing something non-obvious that makes the much better?...
- MaxBarraclough 3y ago
  For what it's worth there's also this 2016 document, Introduction to Reports and Theses. [0] It's clearly different, but the introductions in particular have a lot in common: From the IEEE version of A Guide to Technical Report Writing: > A good report is easy to recognise. Its title is precise and informative, its layout and format are well organised, and the binding is easy to handle and opens flat to reveal both text and diagrams. Reading a well written report is pleasurable: the style is accurate, fluent and concise, with headings to indicate the content of each section. The diagrams, which in this Guide will be taken to include non-verbal material such as tables and graphs, are well presented and clearly labelled. There are no absolute rules about the details of report production, because every report must be totally adapted to the needs of its reader. (The IET version is slightly different, for instance it does not mention document binding.) From Introduction to Reports and Theses: > A report is good when it is easy to recognize, title is precise and informative. The layout and format are well organized. The binding is trouble-free to handle and open. Reading a well written report is pleasurable, if, the style is accurate, fluent and concise, with headings to indicate the content of each section. There are no absolute rules about the details of report production, because every report must be totally adapted to the needs of its reader. [0] https://papers.ssrn.com/sol3/papers.cfm?abstract_id=2775664 https://papers.ssrn.com/sol3/papers.cfm?abstract_id=2775664 or https://dx.doi.org/10.2139/ssrn.2775664 https://dx.doi.org/10.2139/ssrn.2775664
- gen_greyface 3y ago
  its the updated version according to the file metadata . creation date for the second link you shared is `30/01/2020, 15:05:47`
redcap 3y ago
The guide has a section on accuracy but doesn’t talk about having punctuation outside of quotation marks. There’s a world of difference between 1. Please enter the text “foo bar.” and 2. Please enter the text “foo bar”. The first is normal American practice, but suggests incorrectly that the period (.) should be input. Technical writing should be accurate - meaning all quotes should be a true representation that is not subject to style whimsy.
- macintux 3y ago
  I switched to the British practice (punctuation outside quotes) years ago, and no one has ever complained. I have vague hopes that in another couple of hundred years we'll have solved that problem. Imperial vs metric, however, will never go away.
- replwoacause 3y ago
  As an American, I never knew #1 was American practice and have only ever used option #2 my entire career. #1 makes no sense.
bomewish 3y ago
The stuff about having a clear model of the reader and the purpose of the report in relation to them was alone worth the price of admission. Such fundamental advice that applies to all writing — but easy to forget.
moshegramovsky 3y ago
My ultimate technical writing tip is to be like Mike and "just do it". The more you write, the easier it gets. If you write enough to reframe your perspective around the user's problems, and come to a point where you question your technical decisions as a result, then you're definitely headed in the right direction. Documenting something is simply the best way to put yourself in your user's shoes.
aquafox 3y ago
What helped me most is to separate the task of writing content from writing the nicely (copy-editing): https://clauswilke.com/blog/2013/09/22/silence-your-inner-critic https://clauswilke.com/blog/2013/09/22/silence-your-inner-cr... It is also more aligned with how one naturally writes code: Instead of aiming for code or a fumction that perfectly works on the first go, aim for something that roughl, should work and improve it in a later step.

83 points by smartmic 3y ago

The first tip I'd give is don't publish your technical report exclusively as a PDF, because those are bad for linking to, bad for searching, bad for copying-and-pasting out of, bad for reading on mobile phones, harder to crawl and index, and harder to update in the future. If you really must have a PDF at least make a proper web page version first and then link to the PDF as an alternative format for people who really, really want it. (This pet peeve aside, this is a good document with some excellent advice in it.) Another problem with PDFs: since they don't particularly encourage having a single, unambiguous URL you can end up with confusing multiple copies of them floating around. This post links to https://ias.ieee.org/wp-content/uploads/2023/06/2020-01-16_IET_Technical_Report_Writing_Guidelines.pdf https://ias.ieee.org/wp-content/uploads/2023/06/2020-01-16_I... - which has 2023 in the file path, 2020 in the filename and declares it to be copyright 2015 in the actual document. A search for "A guide to technical report writing iet" lead me instead to this document: https://www.theiet.org/media/5182/technical-report-writing.pdf https://www.theiet.org/media/5182/technical-report-writing.p... - same organization, similar content, different document design. Is this the updated version of that 2015 one? Hard to tell, because it doesn't have a date anywhere.

scrlk 3y ago
> Is this the updated version of that 2015 one? Correct - it uses the latest IET branding. The one linked in the submission uses the previous IET logo. PDF metadata also points to that document being created in 2020.
- logicallee 3y ago
  >Correct - it uses the latest IET branding. it's really much more than that. They laid it out gorgeously, introduced pull quotes, and typeset things so the eye could visually follow the content much more easily, including through text in different colors, bold and various typesetting devices. They rearranged it a bit. They made it a breeze to read through. They also added a bunch of irrelevant stock pictures which have nothing to do with the text and contain no information but somehow still made it much easier to read through. Is the content the same or was some of it omitted? The original PDF had more pages and this one has a lot of photos taking up space, and seems to have more whitespace as well.
EFreethought 3y ago
That second one is a two-column PDF file. The only think I hate more than a PDF file on the web is a two-column PDF file. At least with one-column you can just scroll in one direction.
- deleted 3y ago
  [deleted]
- account-5 3y ago
  I don't know why you're being down voted. Two column articles, pdf or otherwise, are simply harder to reader and know your place. Should be banned. Unless of course I'm missing something non-obvious that makes the much better?...
MaxBarraclough 3y ago
For what it's worth there's also this 2016 document, Introduction to Reports and Theses. [0] It's clearly different, but the introductions in particular have a lot in common: From the IEEE version of A Guide to Technical Report Writing: > A good report is easy to recognise. Its title is precise and informative, its layout and format are well organised, and the binding is easy to handle and opens flat to reveal both text and diagrams. Reading a well written report is pleasurable: the style is accurate, fluent and concise, with headings to indicate the content of each section. The diagrams, which in this Guide will be taken to include non-verbal material such as tables and graphs, are well presented and clearly labelled. There are no absolute rules about the details of report production, because every report must be totally adapted to the needs of its reader. (The IET version is slightly different, for instance it does not mention document binding.) From Introduction to Reports and Theses: > A report is good when it is easy to recognize, title is precise and informative. The layout and format are well organized. The binding is trouble-free to handle and open. Reading a well written report is pleasurable, if, the style is accurate, fluent and concise, with headings to indicate the content of each section. There are no absolute rules about the details of report production, because every report must be totally adapted to the needs of its reader. [0] https://papers.ssrn.com/sol3/papers.cfm?abstract_id=2775664 https://papers.ssrn.com/sol3/papers.cfm?abstract_id=2775664 or https://dx.doi.org/10.2139/ssrn.2775664 https://dx.doi.org/10.2139/ssrn.2775664
gen_greyface 3y ago
its the updated version according to the file metadata . creation date for the second link you shared is `30/01/2020, 15:05:47`

redcap 3y ago

The guide has a section on accuracy but doesn’t talk about having punctuation outside of quotation marks. There’s a world of difference between 1. Please enter the text “foo bar.” and 2. Please enter the text “foo bar”. The first is normal American practice, but suggests incorrectly that the period (.) should be input. Technical writing should be accurate - meaning all quotes should be a true representation that is not subject to style whimsy.

macintux 3y ago
I switched to the British practice (punctuation outside quotes) years ago, and no one has ever complained. I have vague hopes that in another couple of hundred years we'll have solved that problem. Imperial vs metric, however, will never go away.
replwoacause 3y ago
As an American, I never knew #1 was American practice and have only ever used option #2 my entire career. #1 makes no sense.

bomewish 3y ago

The stuff about having a clear model of the reader and the purpose of the report in relation to them was alone worth the price of admission. Such fundamental advice that applies to all writing — but easy to forget.

moshegramovsky 3y ago

My ultimate technical writing tip is to be like Mike and "just do it". The more you write, the easier it gets. If you write enough to reframe your perspective around the user's problems, and come to a point where you question your technical decisions as a result, then you're definitely headed in the right direction. Documenting something is simply the best way to put yourself in your user's shoes.

aquafox 3y ago

What helped me most is to separate the task of writing content from writing the nicely (copy-editing): https://clauswilke.com/blog/2013/09/22/silence-your-inner-critic https://clauswilke.com/blog/2013/09/22/silence-your-inner-cr... It is also more aligned with how one naturally writes code: Instead of aiming for code or a fumction that perfectly works on the first go, aim for something that roughl, should work and improve it in a later step.