5 ms·

Here's a screenshot of FrameMaker I just took: https://imgur.com/a/CG8kZk8 https://imgur.com/a/CG8kZk8 Look at the fancy page layout that was possible in the l

Here's a screenshot of FrameMaker I just took: https://imgur.com/a/CG8kZk8 https://imgur.com/a/CG8kZk8 Look at the fancy page layout that was possible in the late 1980s. Can Word do this today?

digitalPhonix 8mo ago
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?
- lateforwork 8mo ago
  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.
  - ferguess_k 8mo ago
    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?
    - lateforwork 8mo ago
      > 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.
      - ferguess_k 8mo ago
        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.
        WillAdams 8mo ago
        Framemaker.
        ferguess_k 8mo ago
        Thanks, thought MSFT was using its own tools.
        WillAdams 8mo ago
        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.
        ferguess_k 8mo ago
        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.
- WillAdams 8mo ago
  Correct, it is going away as of October this year.
WillAdams 8mo ago
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.
deleted 8mo ago
[deleted]
socalgal2 8mo ago
now paste some Chinese and Thai in there and a few high-res jpegs
kjellsbells 8mo ago
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.
- ferguess_k 8mo ago
  I still wish manuals are written in the old way, like this one: https://archive.org/details/gwbasicusersmanual_202003 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/ https://go.dev/doc/
  - WillAdams 8mo ago
    What is the new way in which manuals should be written? I've been trying via Literate Programming: http://literateprogramming.com/ http://literateprogramming.com/ and applying the concepts of: https://diataxis.fr/ https://diataxis.fr/ (originally developed at: https://docs.divio.com/documentation-system/ 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/gcodepreview.pdf https://github.com/WillAdams/gcodepreview/blob/main/gcodepre...
    - ferguess_k 8mo ago

Here's a screenshot of FrameMaker I just took: https://imgur.com/a/CG8kZk8 https://imgur.com/a/CG8kZk8 Look at the fancy page layout that was possible in the late 1980s. Can Word do this today?

digitalPhonix 8mo ago

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?

lateforwork 8mo ago
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.
- ferguess_k 8mo ago
  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?
  - lateforwork 8mo ago
    > 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.
    - ferguess_k 8mo ago
      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.
      - WillAdams 8mo ago
        Framemaker.
        ferguess_k 8mo ago
        Thanks, thought MSFT was using its own tools.
        WillAdams 8mo ago
        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.
        ferguess_k 8mo ago
        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.
WillAdams 8mo ago
Correct, it is going away as of October this year.

WillAdams 8mo ago

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.

deleted 8mo ago

[deleted]

socalgal2 8mo ago

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

kjellsbells 8mo ago

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.

ferguess_k 8mo ago
I still wish manuals are written in the old way, like this one: https://archive.org/details/gwbasicusersmanual_202003 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/ https://go.dev/doc/
- WillAdams 8mo ago
  What is the new way in which manuals should be written? I've been trying via Literate Programming: http://literateprogramming.com/ http://literateprogramming.com/ and applying the concepts of: https://diataxis.fr/ https://diataxis.fr/ (originally developed at: https://docs.divio.com/documentation-system/ 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/gcodepreview.pdf https://github.com/WillAdams/gcodepreview/blob/main/gcodepre...
  - ferguess_k 8mo ago