Hacker News Reader

Comment by lateforwork | Hacker News Reader

Here's a screenshot of FrameMaker I just took: https://imgur.com/a/CG8kZk8

Look at the fancy page layout that was possible in the late 1980s. Can Word do this today?

I didn't have defending Word on my todo list today,... but Word would totally be the wrong tool for this,so it isnt fair to compare.

The tragedy is that serious large document authoring systems died with the invention of hypertext and the CDROM. Instead of an elegant set of FrameMaker or Interleaf documents for print you got a cdrom with a private site. And then once the web took off, just a site. Something got lost in that transition beyond the pallet of manuals showing up on your loading dock when you bought a system.

Sadly because Word won, technical authors still try to produce some content with it, but (not their fault) it's a horrible broken experience for both writer and reader. One example is the 3GPP specs that define how the mobile phone network works. Giant 200 page Word docs that take minutes to open and paginate.

I still wish manuals are written in the old way, like this one: https://archive.org/details/gwbasicusersmanual_202003

It is not only a dump of functions, but also with examples for each one of them. I think the Go one is pretty good: https://go.dev/doc/

What is the new way in which manuals should be written?

I've been trying via Literate Programming:

http://literateprogramming.com/

and applying the concepts of:

https://diataxis.fr/

(originally developed at: https://docs.divio.com/documentation-system/) which divides documentation along two axes:

- Action (Practical) vs. Cognition (Theoretical)

- Acquisition (Studying) vs. Application (Working)

resulting in a matrix of four things

- Tutorials

- How-to Guides

- Explanation (of the code)

- Reference (of the code)

which seems to be working well for my current project: https://github.com/WillAdams/gcodepreview/blob/main/gcodepre...

Yeah I think that's pretty good. I'd say Reference + Explanation + Examples is good enough, like the GWBASIC example -- it doesn't give tutorial-size code, just snippets for each function. But having a tutorial section is definitely more helpful.

I think Publisher would be the equivalent to FrameMaker from the Office suite. Publisher from Office ~2016 could definitely do that.

Unfortunately I think Publisher has faired even worse than Word in terms of stagnation, and now looks to be discontinued?

Publisher is the equivalent of InDesign. It was meant for brochures and so on. If you want to write a long technical manual today most people use Word. In that respect we are using less powerful software today than our grandparents.

Note: Adobe bought FrameMaker and continues to sell FrameMaker. But Word has captured the market not because of its technical merit but because of bundling.

I have never written any technical manuals, but I'm surprised that Word is the choice of tool. How does one embed e.g. code easily in the document? I feel there must be a better way to do it, maybe some kind of markdown syntax? Latex?

> How does one embed e.g. code easily in the document?

You don't. For APIs and such, documentation is published online, and you don't need Word for that. Word is used in some industries, where printed manual is needed.

What about the printed manuals? I think they still have some of those not too long ago (e.g. Intel manuals). What was the tool chosen? Very curious to know.

Or, maybe a legacy example -- how were the printed manuals of Microsoft C 6.0 written? That was in the early 90s I think.

Framemaker.

Thanks, thought MSFT was using its own tools.

If you don't make it, you can't use it.

Microsoft has never made a technical publishing package, so it has to be outsourced.

Yeah I agreed. Kinda missed the old days with thick manuals. I bought one for gdb a couple of years ago and love it -- despite it is just the paper version of the online one.

Correct, it is going away as of October this year.

Yes, Word could do that, but it wouldn't be pleasant to set up or maintain or print (it would re-flow, badly every time one changes print drivers), moreover, there are only two states for long Word documents which include graphics in my experience: corrupt, and not-yet corrupt.

now paste some Chinese and Thai in there and a few high-res jpegs

Reply on news.ycombinator.com