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.
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.
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:
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:
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.)
My brother just finished writing a fantasy novel. By the time he was finished, he had created a searchable wiki with every idea, lore snippet, and references logged into his note taking app.
As easily as we would google an event in history, he could bring up the tagged items associated to a chapter, world event, or character in his book.
At the late stages, when he was modifying a lot with the help of his publisher/editor, this was worth its weight in gold.
Amazing level of discipline and wisdom choosing to set it up in that way for himself.
I would recommend similar to anyone considering writing a book.
His book was recently published and is sold in stores everywhere under the title “Gods-Forged”.
Yes I've suspected for a long time that this is really what you have to do. Either you are so immersed and have such a good memory that you live in your own fantasy world every day... or reality sets in and you treat fantasy worlds just like the real world, I mean that's what you want after all: For it to feel as real and believable as possible. The real world is pretty complex and full of details, facts and history and lore. Doing this without a database or without treating it like a historical research project is futile. You'd never hope to archive the entire lore and history of e.g the aztek culture in the real world without writing it all down. Hoping against hope that you'd somehow manage to make a believable window into a whole fantasy culture without having a far bigger corpus available at all times so you can adjust that window is futile. After all you have to move that window around for the story to develop and if there is nothing behind it, you constantly have to invent new things adhoc for every millimeter that you moved it. It's too hard.
> At the late stages, when he was modifying a lot with the help of his publisher/editor, this was worth its weight in gold.
I know a developmental editor, and occasionally we bond over the the overlap in our fields of resolving rafts of conflicts between versions of big text datasets.
I remember I once showed off Mediawiki as a "just so you know this kind of cross-referencing tool exists", but I think they have their own note-taking strategies.
This was such a great pitch for the book, I went ahead and ordered it!
With fantasy settings in particular it's crucial to keep the setting consistent, since the book is the only "source of truth" on the matter. This sounds like the way to go. Excited to check it out.
What are you guys writing that your thinking speed outperforms your writing speed to the point where you have to optimize your software and hardware?
In my (very minuscule) experience in writing 99% of the time is spent switching between browser, scratchpad, notes, and standing up to take a walk and think about it.
Start with the minimum possible format you can (plaintext) and step up a standard when necessary. The simpler the standard, the more software there is that just works with it.
Settings > Accessibility > Slow Keys on MacOS. Turn that on and set the delay to maximum. Now, presumably there's a number that annoys you, and even though you spend most of your time switching between apps it will annoy you when you write. So if you get annoyed there, you must imagine that there is some bell curve of reaction speed. Absent any information, it's worthwhile to imagine you at the center, a pretty median slow guy. In that universe, there is some guy who will be three standard deviations faster. Just like you were annoyed when Slow Keys was on, he's annoyed when he's in the usual mode.
> In that universe, there is some guy who will be three standard deviations faster. Just like you were annoyed when Slow Keys was on, he's annoyed when he's in the usual mode.
Reminds me of how my son watches youtube at 2x all the time and probably would crank it up faster if there was a higher option.
And I totally agree with your son, YouTube and Podcasts are sometimes just slow or waste time with irrelevant/boring information, and changing the playback speed is a highly underrated way to deal with it. You do get used to 2x after a while.
I prefer the much simpler Video Speed Controller [0][1]. It works on YouTube, but also on every HTML5 video component on the web, including streaming platforms like Netflix/Prime/Disney+. No more wishing that a particular platform supported speed controls.
They did make it sound like a lot of work. Having done it a few times, I found it easier to write in a word processor. I prefer LibreOffice. I’ve also written in Markdown and HTML, but, for me, a word processor was easier because of the other items they mentioned needing. You can add front matter and Table of Contents easily in a word processor like LibreOffice.
In fact, I have a very short book about my step-by-step process on how to format and publish your own book with LibreOffice.
I recently wrote a blog post giving the cliff notes version of the book in a couple pages but I seem to have accidentally deleted it. I need to go dig it up.
I don’t think thinking speed outperforming writing speed is a necessary condition for wanting to optimize the software and hardware. Speed is rarely an issue.
I’d say ergonomics, organization of information, and the “feeling” of using the tools are the driving force behind all these efforts of optimizations.
I'll second the asciidoc approach. After my wife was killed by a Russian tank in Ukraine, I collected up everything she wrote (she wrote a LOT - I've collected 250,000 words so far) and needed to compile it into a book in a way that allowed easy edits and arrangements.
Asciidoctor was a godsend in this regard, able to output in PDF, EPUB, MS Word, whatever you want.
With Asciidoctor, ImageMagick, FFMpeg, LibreTranslate, and about 800 lines of Python code I'm now able to generate any part of the book draft in any language (this is mainly to build excerpts for publishers).
I write fiction using Markdown + Git and love the workflow. Now it's kind of strange treating the whole thing like a software project and having each chapter as a seperate file (along with other folders for notes, artwork, etc.) but it's easy to work with, self hostable, and the entire repository with all its history can easily travel with me on any device. It even has a Makefile to spit everything out as a PDF!
This is also what I do. I use markdown+git for all kinds of writing. I use Obsidian with tons of extensions. It's integrated with my personal knowledge base, notes etc. If I'm writing fiction or poetry, one file is one chapter/unit, but sometimes if I'm making huge changes, I'll rename that file to "Chapter X Draft 4" or something like that, so that I can instantly see very old versions without git. If I want to look at the full history git history on "Chapter X" will give the entire thing. It's also nice to write tiny scripts to assemble finished chapters into volumes etc and auto-convert to PDF.
I also do literate programming (write code as if it's a book written for your future self) with this exact same approach. Just write a two line script that removes everything that's not between ```python ``` and you can code inside Obsidian. (E.g. you can use a markdown parser like `marko` for python) I personally don't need syntax highlighting, but if you do, you can open it in your IDE/Emacs/etc and IDE should highlight most languages in Markdown files. You obviously don't get all the IDE bells and whistles, for those you can have separate files and import them in, or enable Python mode in markdown files (somehow). (Obsidian should support basic syntax highlighting for most common languages anyway)
Since Obsidian is so awesome, this approach has endless possibilities. E.g. you can do project management inside Obsidian via Kanban board, you can use Excalidraw tool in Obsidian to draw architecture diagrams, write music inside Obsidian with its Lilypond plugin, write math with LaTeX plugin etc. It just automatically works out of the box.
I too use markdown + git for everything. I checked out Obsidian one day, it appears to be a wiki with tags to me, while it's great to do notes taking for some, it seems to be less organized for myself, and it's hard to use it for books, which is more streamlined by chapters etc, am I missing something?
Obsidian is an extremely extensible and customizable software. Truthfully, there is no text editor as customizable as Emacs, but if you're looking for something other than that, Obsidian is pretty close to being "Emacs for Markdown". I use Emacs for coding but I'm not a fan of the orgmode so I use Obsidian for note taking, and writing things.
You're missing something. Obsidian is amazing for writing and research because of all of the automatic linking between things. If you're already using markdown and git for writing, then Obsidian is worth another look because you can pick and choose to enable what options help your workflow.
As an example, let's say you tagged every time a character is mentioned (will be done automatically as well with 'untagged references' for proper names). Or you have all of your backstory and timelines in sections that are linked to your writing, but you can output the finished writing without all of those links in there. So as an author you get a full timeline with metadata. You can also use additional tools for research with Obsidian plugins, including Zotero for academic references, Markdownload Browser Extension for shooting MD and images straight into your vault, git plugins inside Obsidian, etc.
Sorry I'm rambling, but absolutely go look at it again!
The last screenshot shows a single source file having multiple themes applied, one being a manuscript theme.
The editor integrates variables in an external file so that if I want to change a character's name, I can do so in one place. Even diagrams (e.g., family tree) are updated.
Out of curiosity, do you use any specific version control features when writing like this outside of history which is just kind of there by default? It would be hilarious but amazing if you said your editors (if you have any) give you feedback in the form of pull requests.
Yeah that would be awesome but sadly they'd just be confused and annoyed by it all. I mean in my writing communities I'm the only one that uses Git, Linux, and MD. Everyone else just sticks with Google Docs, Word, or some more specialized writing apps.
I sometimes use Git branches to explore different story ideas but I mostly just use the system for basic versioning and history. I also use Git for written roleplays to store my logs and thoughts, and since MD is basically text I can use Unix tools like grep and wc.
I literally just wrote a script to handle my Markdown->PDF workflow: https://github.com/oddevan/periodical "Finished" it today and then saw this article. :/
It's great to hear about someone else using AsciiDoc! We use it for all of our documentation at Oxide, so I had assumed that it was ubiquitous -- and it was only when we had a recent podcast episode about our RFDs[0] that I learned that it was really much less broadly used than I thought! Anyway, we're big fans of AsciiDoc; glad we're not (totally) alone!
Typst[1] is, imo, worth adding to the conversation. I recently used the CLI (and VSCode extensions) to put together a flyer, and I am testing it for invoice generation. So far I am quite enjoying it as a way to put together PDFs programmatically.
Using Quarto on top of Typst gives you all the media size and layout options of Typst along with quickly pivoting or adding on other outputs using Quarto. https://quarto.org/docs/output-formats/typst.html
Though I use Typst on its own for my CV since I primarily needed it in PDF. Almost every other project I create starts with `quarto create project`. https://github.com/mintyfrankie/brilliant-CV
I just ported my md to pdf (via LaTeX) to use Typst. There are still a few nagging issues but overall Typst is 10x better than LaTeX (for my needs which is writing technical books like Effective Pandas).
I came here to say the same thing. I have some experience with both asciidoc and typst and anybody uses/tried using asciidoc should try typst and see for themselves how good it is.
In regards to Markdown, it is nice but not many publishers are going to work with you if the book is in that format. Odds are you will have to convert it to Microsoft Word so the editors can add recommendations, version control, ask questions, apply templates, etc. I wrote a book in Markdown and converted it to Word after the third revision because editing was so painful.
> so the editors can add recommendations, version control
I assume this means the internal versioning features that Word offers, and not something like Git. I sympathize, I imagine the editing process was rough.
It's honestly not that bad if you have a good relationship with your editor. Git really emphasizes word by word or line by line changes; while publishing, at least in the earlier stages of working with an editor/agent, is much more focused on complete drafts. Getting down into the minutiae of word or line edits usually happens rather late and with a copy-editor.
Saving complete drafts, then receiving marked-up copies, worked fine for fiction, at least in my experience. They've been using Word for decades at this point so it's quite formalized. You just follow their instructions (even with file naming conventions). Trying to get a publisher up to speed on Git while your editing is usually just not worth the hassle.
Technical writing, though, is a different story. Managing code blocks is pretty essential in git, in my experience. But then you have specialized publishers for those.
Word makes the world go round. Perhaps specialized publishers will accept LaTeX, but most of the industry does not. Writers need to plan to transmit their manuscripts in DOCX format and to receive notes back in the same format. Of course, something like LibreOffice may be compatible enough, depending on how comments are handled.
How does one write something like a math textbook in Word, I'm curious how it's even possible. Do you handwrite every single formula in the point-and-click UI, wouldn't that be extremely time consuming and expensive?
When I wrote my PhD thesis (the closest thing to a book I've ever worked on), I used LyX and I loved it. All the power of LaTeX, with a usable UI. When you're done, just apply the publisher settings and you're out!
Back when I did composition for STEM publishers, the one manuscript I got in LyX stands out as the cleanest, and easiest to work with --- added two custom packages:
- first loads some packages and defines all the customization commands to do nothing
- second defines the customization commands and applies the formatting as specified by the publisher
Edit the LaTeX text, add customization commands for shortening/lengthening paragraphs, &c. for balancing pages and tweaking float placement --- make PDF, send to printer, then at the end of the project, comment out the second package line and return the updated source to the author for their next edition.
>We knew up front that, whatever solution we picked, it should be accessible, easy-to-use, free and preferably open-source.
I'm not a Microsoft Word fan, but why does their tool need to be free and open-source?
They went to great lengths to explain how the performance of the tools is so important; only to exclude anything you might have to pay for or is closed source.
Who cares if you have to shell out a few bucks for something if it works well and provides great value (i.e. saves you more time and hassle than the money you paid for it)?
Some people prefer to shape the world also by choosing their consumption habits, e.g.:
- encourage development of libre software, to reduce entry barriers for newcomers, allow experimentation, sharing knowledge and reducing trillion-dollar companies dominance
- commute with bicycle or electric vehicle, so the planet lasts longer, and anti-liberal governments controlling the resources enjoy our money little less
- don't plan holidays in countries which are stuck in teocracy, autocracy or exploiting their citizens (N Korea, SA, China...)
- don't buy products originating from such countries, or produced with use of child labor or animal suffering
"My life amounts to no more than one drop in a limitless ocean. Yet what is any ocean, but a multitude of drops?"
I write literate technical docs[0] with Emacs' Org-mode, a plaintext markup language that works well with Git, and exports nicely to LaTeX/PDF to create stunning documents with tables of contents, footnotes, page numbers, headers, footers, and all the usual niceties you'd expect from LaTeX.
Many people can appreciate Org-mode the format, but aren't fond of Emacs the editor, which can be a hindrance to collaboration. The way I get around this in a professional setting is that while I'm working on documents and gathering feedback on them, I take pains to ensure that I can export snapshots to OpenDocument Text format--which can look nearly as good as LaTeX. Google Drive can import documents in ODT format and subsequently Google Docs renders them quite nicely. I accept feedback via the "suggestions" mode of Google Docs, and only after I incorporate the changes in the Org mode source do I accept the changes in the ODT/Docs version.
I can sympathize with the OP authors' frustration with Markdown and resulting preference for ASCIIDoc (try to format a poem, or a play script, in Markdown). Lots of people have addressed this, and NIH rules supreme -- see reStructured Text[2].
However several comments here mention the convenience of a workflow based on Markdown + GIT. Exactly that workflow is the heart of Leanpub[0]. That site facilitates writing into text files organized and stored on Github (or Dropbox), compiling at any point to a finished-looking e-text, which you can then sell via their storefront[1], or take the finished ebook or pdf to a different platform. Leanpub supports their own Markdown variant (sigh).
To be honest, I don't understand the author's hatred of LaTeX. Maybe the experience is very different than 10 years ago? Today, if you use Overleaf, the experience is not so different from that of Google Docs / the online markdown editor. If you really want a styling other than the default one, there are a bunch of templates you can choose from. You get document history and almost real-time rendering, and you can sync to GitHub if you want. You can self-host the front end. Given Pandoc, you can easily convert it to Word; it is one of the most portable ways to write in an open format. You can collaborate on it. Honestly, it's the easiest way for me to open the browser and edit.
I use Vellum. It converts to PDF and EPUB, which is all you need for self-publishing books (I don't know about other destinations). I'd never heard of ASCIIDOC.
Finally, one thing that I really, really wanted, and YMMV. There's no reason why you should care about it, but I did: drop caps (the first letter of a section is 3 or 4 lines tall). I just think it's cool. You could do it with a lot of machinations in Scrivener, but it's trivial with Vellum.
Vellum knows all the things about publishing conventions. What I prefer about it is, you pay money for it. That gives them a stable business model.
Yet to be mentioned here is writing with pen and paper... Anybody still do that? If so, what's your approach?
When writing an essay, I often start with pen and paper. Mostly, an outline, and sometimes also the introductory couple of paragraphs. But I switch to a word processor when the bulk of the words start flowing.
I re-learnt how to write as an adult, after a hand injury, using this handwriting manual from the ~1920s[1]. Shows positions for holding your hand, arm, etc. as well as exercises for practicing the various strokes involved (for English).
LaTeX in a repository can be accessed also using Overleaf which is a cool online platform that takes out a lot of the hard things about LaTeX. I highly recommend to anyone that haven't yet tried Overleaf to use it.
As a big advocate of Asciidoc myself, I have to say this sounds backwards to me too.
I can't imagine someone calling themselves a developer finding writing asciidoc difficult. It isn't any harder than markdown. It only has a slightly different syntax[0], and more features.
I've also faced a lot of resistance from people when asking them to migrate from markdown. My, unfavorable, opinion is that it's simply the usual reluctance to change and unwillingness to learn something new, deal with the short term pain of learning, despite longer term advantages.
* The ordered list isn't the best way to write numbered lists. Numbered lists can be: 1. 1. 1., etc. The computer will auto-increment.
* Typographic quotes are an extension. I wrote KeenQuotes[0] to solve the quote curling problem and integrated it into KeenWrite[1].
* Document header. I fundamentally disagree with putting formatting instructions into plain text documents, in either AsciiDoc or Markdown. I wrote KeenWrite to completely separate the two. Documents are typeset using ConTeXt[2] and a theme[3].
* Admonitions. Pandoc (and KeenWrite) supports annotations in Markdown. I used them on page 5 of my Impacts Project[4] to insert the spectra. I'd say that annotations are more flexible than admonitions because admonitions are often canned (TIP, WARNING, etc.); whereas, annotations are user-defined.
* Sidebars and block titles imply presentation. These are also handled by annotations.
* Includes. You can use R Markdown to get includes. Or write an extension. Fair point that it isn't bundled, though.
* Custom CSS. Again, avoid mixing presentation and content. Specific presentation logic can be applied by annotating the content, rather than trying to format plain text as though it was HTML.
* Definition lists. Supported by Markdown, I use them for a glossary in a novel I'm writing.
* Tables. While perhaps not CommonMark, basic tables are widely supported by almost all Markdown implementations.
There's a fair amount of incorrect, biased, or outdated information on that page.
Here's an example page written in Markdown and made into a PDF:
With that architecture, the source document format doesn't matter. Take any input document, transform it into a structured document format (such as XML), and then typeset it. Pandoc has a similar architecture.
I think you are talking to the right audience who will be excited about all the tools you shared. But to me all these things get in the way of writing. I wrote my first book (short story) entirely on gedit 2.x. It's only when I completed it that I started to use tools to automate publishing. Markdown, auto epub, html, and what not.
These tools are a distraction to the process. I just posted another book I'm writing on github and was asked to share a link to it. Now that an audience is actually watching, I spent countless days building tools around it rather than writing the content. It's nice and all, but I better get back to writing the book or I'll have a beautiful pile of code that does nothing. It supports markdown though...
Is anyone using Msty to ingest your Obsidian vaults so you can chat with your notes? This looks like it could be a powerful method for AI-assisted long form writing, technical or otherwise.
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.