1. 25

  2. 10

    One of the biggest problems I had when writing technical books was how to include code into the manuscript.

    We started by copying and pasting the code, but this is error-prone, untestable, and hard to update. I don’t love writing my books in executable “notebooks” because they tend to enforce a linear coupling of the text and code – but learning any non-trivial program is a graph traversal, not a top-down reading of the code.

    So instead we used a pre-processor to import code by line numbers (e.g. import lines 5-10 from foo.js here). This helps a ton in that the code is on disk, we have no copy-and-paste errors, and we can test it. The problem, of course, is that if you refactor the code or add a line, all of your line numbers are off for the rest of the chapters.

    So I took the path this author avoided and wrote a new tool: cq. The idea behind cq is that you use CSS-like selectors to semantically extract code blocks. How it works is that it parses the code into an AST and then you can extract the code blocks you need semantically rather than by line number. (It currently works w/ JavaScript, ES6, TypeScript, and Python.)

    It’s been hugely helpful in our book writing process because we can update or reformat the code and the code blocks in the manuscript automatically stay in sync!

    I have tons of examples in the README here.

    (While I’m here, I’d like to mention that I’m looking for an author to collaborate on a book for Golang and another on Rust. If you’re interested, DM me or read more details here)

    1. 1

      Oh, this is excellent. I’m gonna see if I can use this for tutorials / blog posts. It could squash a lot of the yak-shaving that (partially) keeps me from writing.

    2. 4

      I’d like to know what people are using for the diagrams I always see in these books, and in technical presentations.

      The ones where we have a nice diagram of a data frame and its fields, or of a stack and how the frames are aligned in order.

      Are people just preparing these in GIMP or is there a simpler answer for vector graphics like these?

      1. 2

        I think people typically use LaTex for these sorts of diagrams. You can also use a tool like plantuml to generate a certain class of diagrams.

        1. 2

          In LaTeX there’s TikZ; in groff there’s pic; in markdown/html you can try ditaa or some later implementations of a similar idea (quite a lot of reinvented wheels, most of them interesting). Other than that there’s dia or other standalone apps for drawing diagrams. Then, there’s Inkscape, Adobe Illustrator, and other generic vector drawing programs. And finally, you can fall back to raster drawing.

          1. 1

            I’m not sure what people are using in general, but the author is using Monodraw for some of his diagrams.

            1. 1

              A lot of Mac users use omnigraffle and I bought a license this year. On the surface it doesn’t appear to be extraordinarily feature ridge for a vector drawing tool, but it is incredibly good and fast for drawing illustrations for technical documents.

            2. 1

              I haven’t written a technical book (yet), but I have read the books Matthew Butterick wrote using Pollen and they look nice enough that I would probably try to use Pollen before homebrewing something.

              1. 1

                I wrote my thesis in LaTeX, which got converted into a book. The publisher, who is technical (not O’Reilly) and you can probably find the book if you doxx me hard enough, made me convert it into Word so the editor could leave comments. The editor would never actually do the edits, just leave comment after comment, which drove me nuts.

                It was not a good experience. I wish I could have just gotten a LaTeX template or Pandoc or something.