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.
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.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.
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.
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.
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.
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.
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.
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.
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_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.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.