These days now that I'm fully in charge of building my own product, I often wonder if we place too much emphasis on centralized documentation sites that users have to deliberately seek out and visit vs in-context documentation snippets that show up as closely as possible to where users might actually need them, deeply integrated into the product and user journeys.

Users don't search for documentation for the sake of finding documentation. They search for documentation because they want to know how or if our product can solve a particular problem they have. My hypothesis is that the documentation discoverability problem is really just a symptom of the product discoverability problem, and that centralizing docs in 1 searchable website to make docs "discoverable" is only addressing the symptom, when that effort can be much better spent addressing the root cause by making the product itself more discoverable and deeply integrating useful documentation into it.

> centralizing docs in 1 searchable website to make docs "discoverable" is only addressing the symptom

a searchable docs website is the most important thing for me. having to "discover" an api by stepping through code and comments is a waste of time--only useful when you already know the basics, which requires documentation

Centralized documentation is valuable for several pieces:

* Easily get an overview of the entire API. I may just be scouting the library, so I want to understand what the API looks like.

* Examples as a starting point. How do I use your API?

* Makes your product more discoverable / approachable to potential users.

Think of your users like a funnel - how are they using the library? What are the common reasons you’re losing potential users? What are the common reasons you’re losing existing users? Users are also different so you have to analyze by cohort.

Now can something better be done? Maybe It takes a lot of work and would have to address the above issues and I don’t know if it would necessarily change the need for something centralized.

I read the documentation before downloading anything, to find out if the software will work for my problem. I’m not sure that “in context” helps with that?

That’s what kaseya is doing with their software, basically having contextual assistance for each feature as an “AI Buddy”, where users can choose to listen/learn or just continue using the product, all integrated as one

I think it's because documentation (and design) requires different skills than writing code. A great programmer is not necessarily a good writer or designer. There are rare gems, people who have a balance of such skills, but most of us struggle to write useful documentation, even the bare minimum necessary for others to get started - or any at all. The code, or the lead dev's brain, is the documentation.

A perfect example of this is documentation generated from docblock comments. Some projects only have such docs, and expect users to go from there. It's as if programmers envision their audience as another machine to program.

I feel similarly about business/marketing aspects of software projects. Many programmers seem to assume, "If you write it (the program), they will come."

Successful software is so much more than just the code, it usually involves a communal effort of various skills, especially human communication, including writing good documentation.

Because being a small project with limited resources requires devs be as resource efficient as possible. Docs, demos, tuts are all super important but it creates an additional maintenance overhead - if they are not maintained up to date, they become worthless.

So for the early stages of a project it makes sense to keep the overhead low and work with a small group of focussed early adopters.

As projects grow, mature and become more stable, more investment into learning material becomes important. Doing it too early burns valuable resources.

I've learned over time that it's much easier to incrementally update existing docs than it is to add them to a large project from scratch - so every single one of my projects, no matter how small, now has documentation from day one.

As I add new features I update the docs to reflect the changes, trying to keep those documentation updates in the same commit as the tests and implementation.

Since I started doing this the quality of documentation I produce has gone up a ton, because I'm constantly exercising those muscles.

It's been a huge win for my coding quality and productivity too - I don't have to remember as much stuff because I can refer back to the docs, and documenting as I go along causes me to make much better design decisions.

Worth noting: I'm a native English speaker writing documentation in English, and I've been blogging frequently and writing online for over twenty years so I've accumulated a LOT of writing experience. So what's easy for me may not be easy for other people!

Good point but writing and maintaining README.md files for your solo projects is nothing like writing proper docs for big projects with multiple contributors and users. That's a full time job, isn't it?

Writing non-code is easy and fun to me - I used to do it for a living - but when I am pressed to deliver features, documentation takes a backseat. Also, I've never felt like documenting other people's code

The two largest projects that I write documentation for are https://docs.datasette.io/ and https://sqlite-utils.datasette.io/ - they're both big projects with multiple contributors, though most of the commits are still from me.

I find the same approach I take to READMEs for smaller projects scales up pretty well: any time I make a change to one of my larger projects I ensure that the documentation is updated as part of that change.

If I accept a PR from someone without documentation I'll follow up by adding the docs for it myself in the next commit. I think that's more reasonable than demanding people add documentation if it's not necessarily their core skill set.

Honestly, I'd love to experience working with a professional technical writer on this kind of thing, but that's not something that's happened at any point in my career to date!

This is good advice, thanks. Really want to practice my writing more as well.

> As projects grow...

I'd argue if should replace as. The point being docs are all but essential for growth (and added participation). To neglect them is self-defeating.

Put another way: Docs are an investment. They have a known return.

Again, we've seen this. We know this. Yet again and again there's case after case of docs denial.

I've been working on my OS library for 9 years now, almost entirely by myself. For the majority of that time I kept documentation separate from code. Now I do enjoy documenting stuff - I have diplomas in both Computing, and Creative Writing - but my various approaches to documenting the project would start off with the best intentions but soon enough degenerate into an irrelevant mess as I tweaked code, forgot to update related webpages and demos, etc.

In 2017 I stopped working on the project entirely: I'd coded up a new major version of the library but never released it because knowing I had to overhaul and re-document so many different pages, demos, etc ... like a dementor, it sucked all joy from me.

Then in 2019 I recoded the entire project from scratch. This time I thought about the documentation first, before I wrote a line of code. I decided the best approach was to generate the main documentation from inline comments. I did this for both core code, and for demo examples - the demos stopped being standalone afterthoughts and became instead my end-to-end testing suite. To present the documentation to any developers who might show an interest in the library, I coded up the library's website in a way so that the core documentation[1] and the demos[2], with easily accessible code, could be very easily copied over to the website whenever I rebuilt the library (which regenerates all the documentation). I also added a set of lessons to the website, and a set of "How do I" articles - both of which are an ongoing project.

The library's website doesn't have any functionality where users can ask questions - but that's what the GitHub issues and discussions pages[3] are for.

The system isn't anywhere near perfect (I still need to automate the demo testing, for example, and there's no CI for copying stuff from the repo over to the website, etc) - but, given the depressing messes I've managed to fall into in the past ... it's working really well for me!

[1] - https://scrawl-v8.rikweb.org.uk/documentation/

[2] - https://scrawl-v8.rikweb.org.uk/demonstrations/

[3] - https://github.com/KaliedaRik/Scrawl-canvas

The boring (and probably mostly correct) answer is that engineers don't like writing documentation so it is the last thing to get done, if it gets done at all. This is especially true of FOSS projects. You may be motivated to spend your free time hacking on something cool and interesting, but spending your free time writing documentation is another matter.

Many engineers do not value good docs, even if they say they do.

Many people won’t read them at all, no matter the quality, and so it can feel like work wasted.

Plus writing docs is a different skill set than writing code that many simply don’t like to do.

Because a poorly-documented product that does something, is much better than a well-documented product that does nothing.

Engineers have to decide where to spend their time, and taking time away from feature development when your early-stage product doesn't have many features is not a winning move.

> a poorly-documented product that does something, is much better than a well-documented product that does nothing

not necessarily. with the latter, you know the constraints of a solution and can make an accurate judgment on whether it's worth using

True, but if it’s too early for a good documentation then talking about taking someone’s crown is too early as well.

It’s not fun to write documentation, and for documentation to be good, it has to be persistently updated.

It takes a lot discipline to do things right.

Agree. But it’s not either/or. I invested easily hundreds of hours in docs before launching TinyBase.org - but I don’t think it made the subsequent community building challenge any easier.

Yes, fair enough. And I'd like to add

Docs !== community

Docs === Odds of gaining traction

To your point, achieving community is a whole other beast to battle.

Because people are "scratching an itch", not creating a product. Most engineers are terrible at writing documentation.

True. Adding tho' that the original topic isn't a side project. It's a team bringing something to market and looking for participants.

And to your point, writing docs *is* something to consider when building the team. As is making sure the culture has a reward system if such behavior is important.

> This is one of engineering things that happens year over year. We all understand the value of good docs. Yet it keeps happening. Why?

Because doing anything is is irrational?

Time is finite, only a rounding error number of projects (especially open-source ones) are going to be successful, with or without docs.

Only an irrational developer would think that they are going to hit the 1-in-a-thousand jackpot with their project.

Any time spent producing documentation is time not spent on adding features and fixing bugs.

Spending time on documentation over and above the bare necessity needed to get out a working product "just in case we win the jackpot" is simply irrational.

This is probably why you don't find many projects spending significant startup time on good, clear and comprehensive docs (as opposed to a README and an FAQ and nothing more): the ones that do as you suggest mostly die before even getting users.

TLDR; don't treat your startup project as if you already have 5m users who depend on you. The odds are that you are never going to get to that point without a good product, and the better the product, the fewer the docs needed.

because time is finite

if you spend your time making sure your product works but don’t write thorough documentation, it can become a breakout hit even though some hacker news commenters may complain about a lack of good documentation

if you spend your time writing great documentation, the product will suffer and nobody will use it

> if you spend your time writing great documentation, the product will suffer and nobody will use it

This is an unfortunate perspective. And I could say the opposite is true. If you don’t spend time writing great documentation, your product will suffer and nobody will use it.

Documentation gets neglected because developers don’t feel like doing it. If you are building a product for developers, documentation is critical.

Docs aren’t the fun part of dev.

They are more fun to me than writing tests

Unless you make it programmable