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.
Follow me on Twitter
Follow me on Blue Sky