This is one of engineering things that happens year over year. We all understand the value of good docs. Yet it keeps happening. Why?
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.
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
* 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.
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.
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.
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!
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
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!
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.
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/
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.
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.
not necessarily. with the latter, you know the constraints of a solution and can make an accurate judgment on whether it's worth using
It takes a lot discipline to do things right.
Docs !== community
Docs === Odds of gaining traction
To your point, achieving community is a whole other beast to battle.
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.
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.
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
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.