Comment by simonw | Hacker News Reader

Comment by simonw | Hacker News Reader

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

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 or https://dx.doi.org/10.2139/ssrn.2775664

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

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

its the updated version according to the file metadata . creation date for the second link you shared is `30/01/2020, 15:05:47`

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.

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

Reply on news.ycombinator.com