Re: Engineering Textbook: Word MasterDocs vs FrameMaker vs ... ???

["Elisa R. Sawyer" <elisawyer -at- gmail -dot- com>]

Just a FYI for people who might like to know about professional quality pdf
output from open source tools, here is a repository that I created for
RISC-V that contains information on making use of AsciiDoc with the
Asciidoctor toolchain:

https://github.com/riscv/docs-templates

Yes, there's a learning curve, but from my POV it's not more complex than
Framemaker.

I have made use of AsciiDoc in several projects. It's gaining in
popularity, especially for DevOps documentation and also for integrating
the docs build with Swagger and OpenAPI.

I've discovered, over time, that developers tend to think that solving the
problems of publishing documentation might be a cool problem to tackle.
They tend to have the opinion that it's an easy problem to solve, until
they are actually several months into their "solution." I've seen this
happen more times than I can count.

There are two lightweight markup languages that have significant
followings, and each one of them is good:

- Restructured text, using Sphinx-doc for the build.
- AsciiDoc, using Asciidoctor for the build.

The repo I referenced above is open source and I created it around the
needs of RISC-V. I am thinking that I could, when I have time, create a
separate repo for writers with a bit more information and guidance on
customizing the look and feel.

I have seen that there is still a need for professional quality pdfs, even
as other formats do meet the needs of many audiences. Asciidoc does enable
single-sourcing and lends itself to integration with CI/CD.

- Elisa




On Wed, Oct 20, 2021 at 2:48 PM Peter Neilson <neilson -at- windstream -dot- net>
wrote:

> Indeed, multi-level subheadings are tied firmly into academic writing,
> making the stuff useless for reading. In literary works three levels are
> about all the human mind can process, and that's when we've got something
> like Henry IV Part 2: Act 2 Scene 3. There, the actors present it in a
> nice linear fashion, and we need not worry that we're absent-mindedly
> looking at Act 3 Scene 2 by mistake.
>
> One of the advantages of numbered subheadings is that a bunch of
> disparate
> authors can write their disparate sections that are all to be scrunched
> together. The blame for the problems in Section 3.4.1.2 can be traced
> back
> directly to Irving J. Jones. He never bothered to read Section 3.4.1.1,
>  from which his contribution is a non-sequitur. But who cares? In
> academia
> nobody except the thesis advisor reads anything but the abstract anyway.
>
> How does the PhD candidate get someone else to write a section? Easy, it
> happens a lot. I edited a paper for an ESL student who copied the bulk of
> his thesis from articles in Wikipedia. I'll bet his committee never
> noticed.
>
> What the heck happened in Henry the IVth Part 2? I've forgotten. Hold on,
> hold on, maybe it's this:
>    Glendower: I can call the spirits from the vasty deep.
>    Hotspur: Why, so can I, or so can any man; But will they come, when
> you
> do call for them?
> No, no. That's Henry IV Part 1.
>
> Even dividing Henry into two parts is more than some minds can bear.
>
> On Wed, 20 Oct 2021 16:29:54 -0400, Gene Kim-Eng <techwr -at- genek -dot- com> wrote:
>
> > If "textbook" means that the finished product is intended for
> > educational use, I would really try to avoid the use of multi-level
> > subheadings. Some of the engineering textbooks from my college days
> were
> > loaded with useful data but were otherwise unreadable.
> >
> > Gene Kim-Eng
> >
> >
> > On 10/20/2021 11:26 AM, Nina Rogers wrote:
> >> The book will be between 400-500 pages with 16 chapters, each of which
> >> currently has between five and ten level-2 subheadings. (As I read
> >> through it, I'm seeing a need for L3 and even L4 subheadings.) There
> >> are scores of figures, tables, and mathematical equations throughout,
> >> all of which are labeled and cross-referenced at least once (and often
> >> multiple times) in the book. There is also a lengthy appendix (case
> >> studies, included in the page count I gave earlier) and, of course, a
> >> TOC and an index. The current version has no table of tables or table
> >> of figures, but we may add that because there are so many. If we add
> >> more heading levels, we may also have a single-level TOC followed by a
> >> more detailed, multi-level TOC. That may not happen, but it's a
> >> possibility. So, lots of cross-referencing, math equation text (I see
> >> that FrameMaker has a "MathML Equation" feature, which is new to me
> but
> >> looks like what I would use for the equations.
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy and
> content development | https://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as elisawyer -at- gmail -dot- com -dot- 
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
> http://www.techwhirl.com/email-discussion-groups/ for more resources and
> info.
>
> Looking for articles on Technical Communications?  Head over to our online
> magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions?  Search our public
> email archives @ http://techwr-l.com/archives
>


-- 
Elisa Rood Sawyer
~~~~~^~~~~~
Technical and Creative Writer
"Apparently there is nothing that cannot happen today." Mark Twain
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | https://techwhirl.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications?  Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions?  Search our public email archives @ http://techwr-l.com/archives