I just spent a lot of time over the weekend restructuring and rewriting a lot of Orchid's documentation, and more and more I'm realizing just how hard it is to write good documentation. It's easy enough to write comments for all your classes and functions, and it's easy enough to write a wall of text about your cool project.

But good documentation isn't a wall of text. It is a carefully-crafted journey through your project with a goal to get people comfortable with it.

Take glance through all the following sites that I consider to have better-than-average or great documentation:

• Hugo
• Jekyll
• Laravel
• October CMS
• Vue.js
• Bootstrap
• Netlify

Did you notice anything in common?

Let me share a few things I've noticed in all these sites that I have been working to implement in Orchid's docs. I am by no means an expert, but I assume the guys who wrote those docs are, and I'm just trying to follow in their footsteps.

Effective Headlines

Your readers aren't reading your docs because it is a riveting novel. They are reading it to find the answer to a problem they have. They don't want to spend a lot of time in your docs; make it all about the headlines!

Note that headlines aren't necessarily just your <h> tags; It's the idea that you should structure your docs in a way that a reader can glance through it and immediately find what they are looking for. Maybe that's optimizing your pages for search, or having an excellent page hierarchy that guides the reader right where they want to go.

But especially, once they've landed on a page, do use your <h> tags effectively, so they don't have to read everything to find the very specific section they need.

Strategic Navigation

Good docs are a journey through your project. It should have a start and an end. And it should have a clear movement from the start toward the end. The later pages in your docs should naturally build upon the earlier.

Don't explain things more than once: refer back to previous pages. And it's OK to tease at more complicated features the reader will find later in the docs, but again, don't try to explain it there! You'll only confuse your audience, just link forward to it!

Know (And Trust!) Your Audience

Those reading your documentation aren't stupid. They managed to find your project, they know enough about it to want to learn more. If they are actually reading your docs, then they likely already made their way through your quickstart and are trying to figure out what to do next.

Stop trying to sell your project in your docs. That's what a README is for. Trust that your audience is already hooked, and just help them go deeper. Furthermore, those reading the docs probably aren't experts in the project, otherwise, they would likely be using the API reference indeed. But that sweet-spot in between novice and expert will make up the largest percentage of those reading your docs, so tailor the docs to them.

Examples Are Better than Words

I won't quite go as far as saying "a code snippet is worth a thousand words", but they are quite important. In fact, let your examples lead the charge in getting your point across, and let the prose simply explain the example.

Keep your examples small, keep them focused, and keep their explanations short, 1-2 sentences at most.

You Don't Need to Document Everything

As the creator of a project, your tendency is to think that every single feature is important. Every feature must be documented. But that's not entirely true. An auto-generated API reference serves to document every feature. Remember: your docs' main purpose is to help the reader go deeper, not deepest.

It is sufficient to just give the reader a high-level overview with a very basic example of its usage, as long as it gets the main idea across. If they need a more thorough understanding, refer them to the appropriate classes in the API reference, or even directly to the source code. But ideally, the individuals going that deep are rare, and they aren't necessarily the primary audience.

Conclusion

I am by no means an expert in writing good documentation, but I have been working really hard to figure this thing out, and I am trying to put what I'm learning into practice with Orchid.

Is documenting Orchid as fun as it is to develop the product itself? Definitely not. But is it as important? Actually, it's much, much more important. If Orchid doesn't have good documentation, then what reason would anyone have in using it? And if no one is using Orchid, then I've got no reason to continue developing it with the level of effort that I am.

So I would love to get your feedback on Orchid's docs and learn what I could do better with it. And especially, let me know any tips you have for writing effective documentation that I haven't mentioned!

• Orchid docs
• Orchid on Github