Comment by lateforwork
16 days ago
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?
16 days ago
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...
1 reply →
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?
6 replies →
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