Skip to content

Monthly Archives: January 2025

When Are You Ready To Write A Technical Book?

This question came up on an HN thread.

My process for any book I’m thinking about writing is:

  • write out 10 titles for blog posts on the topic
  • write 1-2 blog posts (this lets you, in a low risk way, verify you have interest/expertise)
  • add an email list signup at the bottom of the posts
  • do a bit of research to see if someone else has written on the topic (some googling or reddit searching)
  • write the rest of the blog posts

If you can get 10 meaty blog posts, you have the basics of a book. Plus, you’ll know that you are interested in the topic and that you can write. As you wrote those blog posts, you probably had related ideas or areas you wanted to explore.

You’ll also be able to share these blog posts with friends, colleagues and online communities that you may be a part of. You can get feedback on the ideas and the overall topic here.

You can self-publish the book (done that) or use a publisher (done that). The latter will take more time and effort and will require you to fill out a book proposal.

To be honest, even if you are planning to self-publish, doing the hard work of completing a book proposal is useful. Even if you don’t submit it. It forces you to think about:

  • who is my audience
  • what are my core ideas
  • what else has been written on this topic
  • why is what I’m saying unique
  • why am I the right person to write this book

This can help you narrow in on what will make your book successful and can help with your marketing messaging.

What If you can’t write 10 blog posts about a topic? Then you are missing either:

  • interest in the topic
  • necessary knowledge

But it’s more likely the former. Because you’ll have time to do research to learn. I remember taking something like 4 hours to answer one question about how the Cordova CLI acted in one peculiar edge case. It turned into one sentence in my book.

Finally, if no one else has written anything about the topic (no books, no articles, no social media posts, no nothing) and/or none of your blog posts get any feedback (positive or negative), pick a different topic or expand your vision.

Here’s an exchange I had with Patrick McKenzie in 2013. I wrote:

I had a quick question. I was thinking about writing an ebook for a super niche topic (testing ETL transformations using Pentaho Kettle, an open source ETL tool).

I outlined the book, did some google searching and wrote up a series of blog posts with an email list signup at the bottom.

I got some nice retweets from folks in the Pentaho community and have about 8 people signed up to the list. That was a bit disheartening, but a friend suggested that the folks doing ETL work weren’t exactly developers (perhaps more DBAs or business analysts).

I am still tempted to write the ebook, given my interest in the subject–I think it is a pretty cool tool that I wish would replace lots of data munging scripts, and testing software written using Kettle makes development with it much more fun. On the other hand, I wouldn’t mind some income.

Is this too niche a topic? I’ve been a generalist for most of my career, and if I don’t write this now, in 6 months I probably won’t have the desire or knowledge to do it again (though I might find another software niche to write about by then).

His answer was:

I regret that I have absolutely no knowledge of anything you just said. In general, I might suggest something slightly less niche (you can reasonably suspect to sell 2 copies to 8 people, so unless it is going for $10,000 a copy, might want more volume). You’d still learn a lot publishing it but for the same amount of work why not write on a subject big enough to support 100 or 200 people interested in it?

I could have expanded this topic in several directions:

  • focus on more general ETL testing
  • expand beyond ETL and look at patterns for testing data manipulation
  • focus more on the tool and write a guide to pentaho development, including testing

Or, treat the exploration as an end in itself and not write a book. That’s always a valid outcome of this process of experimentation.

Books Content | moore |

Documentation For Devtools

I have been spending a lot of time working on documentation for FusionAuth over the last couple of years. It’s been a learning experience for me. While it hasn’t been a full time position, I have worked on various aspects of our technical documentation. Some of the things I’ve done include:

  • Modifying or extending the tech stack with components or plugins. We used Jekyll and then Astro for our docs. They each have different strengths.
    • Jekyll feels long in the tooth but has a solution for everything because it has been around so long.
    • Astro feels shiny and new and has nice build time errors. It also evolves more quickly. On the downside, there have been times we had to build our own solution because no one had built it for Astro yet.
  • Extracting out common text to share across document sections, including using variables.
  • Reading lots of code and trying tasks with the product to make sure I understood behavior.
  • Building diagrams using PlantUML and Mermaid.
  • Revamping the user navigation and experience multiple times.
  • Looking at common questions that have surfaced from support tickets, sales conversations and the community and writing doc to answer those questions. This serves multiple purposes:
    • Someone can self-serve the answer to their question, using Google, and may not need to talk to us at all. Devs love that!
    • Support or sales engineers can point questioners to the documentation. They can then spend time adding nuance, rather than copy pasting or worse writing answers from scratch.
    • They help anyone in the company understand product features, including people who might work on a different part of the codebase.
    • By being public and used, these docs stand a good chance of staying up to date.
  • Worked on long guides for deep technical topics, such as one about sessions and another about searching. These are fun to begin with and then become more and more repulsive to me over time. I can barely make myself read the final draft “one more time”. But that kind of write-review-refine-hate-publish cycle is so important for quality doc.

I think we’ve done a good job of documenting our product from a technical perspective. One data point: a competitor said that a challenge of using our product is that the doc can be “overwhelming”. I agree, it is voluminous but sometimes confusing; there’s definitely there’s room to improve. But they are critical. Our docs are the main way people find us and evaluate our solution. They are read and referred to by developers inside and outside of our organization.

On the flip side, one founder I respected when I worked for her a few years ago said “no doc is the best doc”. Her reasoning: the goal of any tool should be to make usage so intuitive that there is no need for a user to read the documentation. Hard to disagree with this, right?

Wait, but I just said docs are critical to FusionAuth’s adoption. What gives?

It comes down to what devs want, when. It should be no surprise that devs want different things at different times.

Keith Casey did a good job of outlining it here, saying we need to answer two questions to help sell to devs:

  • How does our tool help developers build something useful or go home?
  • How do we demonstrate that and speed them along?

If we can’t speak to and demonstrate both, we have a toy, not a tool.

Having an intuitive interface primarily helps with the first goal. When someone is using your tool, can they build something useful? If a dev can’t figure out how to move around and accomplish what they want to do, whether that is because of jargon, bugs or overwhelming complexity, they can’t.

Good UX also helps with the second part of the second question. An interface so good docs are superfluous means it is quick to build something.

Therefore, the “no doc is the best doc” founder was right.

However, devs are not always going to take the time to poke around your tool, especially if you require them to sign up or download something. Great docs, in contrast, help with demonstration. A dev will believe your documentation, at least until you give them reason to distrust you. Statements like “tool X can help you solve problem Y” with instructions on actually doing so, help devs. These developers might be evaluating multiple tools, or even just curious and wanting to learn about your solution. Doc can help them decide whether to invest more time and take the next step. It’s far quicker to scan a doc than it is to sign and navigate a tool.

You can also, with doc and example applications, show how to integrate your devtool into existing architectures or systems. This is relatively easy to do with documentation, sample code and screenshots. It is more difficult to do inside an application UX. You can also cover nuanced topics in-depth and using doc in ways that would be tough to do inside an application’s interface.

Doc also helps with discovery via SEO or LLMs, both of which ingest text. Google is the main way I navigate many devtool focused docs.

(Discovery does assume your devtool docs are public. Requiring registration or payment to view documentation is quite a high barrier for evaluation. I’d avoid that unless you have a monopoly or captive market of devs who must use your software.)

Therefore, the “doc is important” experience I mentioned above is also correct.

You want both an intuitive interface and great docs for your devtool. They serve different purposes.

Content Devrel FusionAuth | moore |