[ryanbigg]

The "Writing" section here has huge "draw the rest of the owl" vibes. (I say this as an accomplished author of 10 tech books.)

Yes, it's worth optimising for your productivity. It's not the be all and end all. I've written at my desk with the comfiest chair (A Mirra) I have, and the most ergonomic keyboard for my needs (Ergodox EZ). I write at cafes with just the laptop. I write on the couch at odd but comfortable angles. I write on public transport squished against strangers.

I love using AsciiDoc as the tooling (asciidoctor + friends) give me output that looks decent, and the way I _input_ into that is not mind-breaking like Docbook is. Asciidoctor gives me a PDF which I then style how I like with CSS and then can put on leanpub.com and sell for real dollars.

The way I would put the writing section for tech books is this:

Start with the _topics_ you want to cover. Make these the chapters. Then dive into each topic and figure out what you want to say about the topic. Usually 3-4 main points per chapter. These come out to be your subheadings. Order the chapters from beginner-to-advanced concepts or in a way that makes sense for the book you're writing. For the books I've written it's usually start with a simple base app and then incrementally build things on top of that.

[dunyakirkali]

You're spot on about the "writing" section.

I actually only wanted to focus on the tooling, but that lacked a little body, so I added a little bit on writing.

It actually deserves its own article

[DanielBMarkham]

Thank you for your essay.

Apologies for being Mr. Negative Guy. I hate folks that do that.

But as somebody who is extremely technical and loves tools and coding, moving to long-form fiction writing, I find that every minute I spend on tooling is _not_ writing. It might be good and necessary, and tools can do some amazing things, but it's not writing.

Fiction writing, at least for me, is a bit of organized struggle with my subconscious. My brain would much rather be coding, writing build scripts, creating a huge cross-layered tagging system, commenting on HN, and so forth. That's because "struggling with your subconscious" is not something we teach or emphasize.

There's a really strong allure of tools, process, and tooling that calls to us when our minds don't want to do the work. Buy the product, learn the tagging, follow the recipe, etc -- it's all about hey, don't do the work, have the tool do the work. Don't be a dummy!

But since I don't know the work myself until I create it, there's no tool or process that's going to do anything but distract. Love my tools, spent a lot of time with them. I spent all day yesterday re-creating and re-factoring my build pipeline from markdown to about a dozen different formats. But that wasn't work, not really. It was avoiding work by doing (hopefully) very useful tangential things.

I'd love to write a tooling/process essay or book. I will not. This is why.

[Terretta]

I wonder if your template (love you used GitHub's template tooling!) could also demonstrate that GitHub has a GFA (GitHub Flavored AsciiDoc) by leveraging the env-github directive for things such as your images that otherwise appear as broken in the template:

https://gist.github.com/dcode/0cfbf2699a1fe9b46ff04c41721dda...

To others reading along, admonitions or callouts, noted here as key motivations for asciidoc, are supported in quite a few flavors of Markdown, but specifically GitHub Flavored Markdown:

https://github.com/orgs/community/discussions/16925

This handles Note, Tip, Important, Warning, Caution.

(After years of incremental work, a suggestion last week complains it's not using mkdocs admonition syntax -- it must be a pain to make custom extensions for a global userbase.)

[hyperthesis]

Knuthing it.