Configuration can be a pain. Sane defaults help and smart UIs help not to mention good documentation.
I've been playing with some software over the last week that has wiki for documentation and an active user forum with people willing to help. But it's completely disordered and incredibly hard to discover. Half the battle with usability is making it easy to use and understand.
Documentation is hard because you have to have empathy for the user while holding most of the product's capabilities in your head while you write it. Transfer of knowledge has always been difficult, and when you start changing the rules in the middle of trying to explain how it works, you'll end up with a very large challenge.
I would assume they'll eventually figure it out and improve it. Until then, the best thing to do is dig, dig, dig.
50% of the questions on Stack Overflow are probably because the documentation was not great in the first place. I am surprised how much configuration/installation time I spend on there.
Most companies either do too little documentation (they have a little page with the bare minimum high-level overview), or they do way too much (detailed change request forms for every change, which go into a file cabinet, and are never looked at again). Alas, it's really hard to get people to understand that documentation is good and necessary when they've only ever been exposed to one or both of those systems.
Though I agree that the documentation is comprehensive, that itself can be a barrier. It all seems very deeply nested and enterprisey. I'm often left wanting a layer of noob-friendly UI or documentation, or "You probably want X"-style guidelines that differentiate between typical use cases and non-typical ones.
Compare, for example, the Digital Ocean UI for creating new VMs. It's a much more pleasant experience than the AWS Console for the new user with a small scale use case.
We really have the opposite problem, there are lots of documentations but they are not exactly organized or all up to date. Much easier to fix than not having any of them I would guess.
For many projects, the single biggest hurdle to success/adoption is good, understandable documentation. Many (perhaps most) open source projects have technical capabilities far in excess of their usable docs.
("Read the whole wiki and then the whole discussion forum to understand" is a huge hurdle for new users.)
There's nothing wrong with the concept of discoverability. Having the capability of discovering how to do thing X without referring to documentation is fine. The problem is when users are forced to rely on it because the documentation is trash or nonexistent. That does seem to be a trend and I share your frustration with it, but discoverability and good documentation can (and should) coexist.
I echo the sentiments about documentation. It works great but they really need to verbosely document every command option and usage. They seem like they’re trying so hard to keep the website clean and minimal, but docs are not the place for that.
I want better documentation for all software I use. Just this morning I have spent 3 hours trying to install something. Give me better documentation, make it easy to search.
I have found that even the group I'm in being documentation-heavy, it's hard to read through everything and build the same context that another engineer has all stuffed into their head.
As you mention:
> available and searchable digitally.
Even with 100% everything written down, it takes a while to build up that context, and even carefully written documentation can have subtleties which send a consumer the wrong way.
Things are a lot easier than they used to be, but still not easy-easy.
I can definitely see this issue, Some people just tend to end up "shaping" the software shipped for better or worse. If the org didn't emphasize documentation/knowledge sharing with someoene equally knowledge it would turn out to be pretty horrible
Facts:
- Things like APIs and coding libraries aside, the bulk of documented interface complexity could be made obsolete in a design phase.
- Blaming users is usually what happens when developers don’t understand why their software is poorly designed.
- Most open source software doesn’t even have a design phase— it just gets built, and the warts get documented… hopefully. And if those warts change, the docs get updated… hopefully. Also, documentation is difficult to write, especially for a non-developer audience. Companies that make products with unavoidable complex interfaces or configurations have departments of technical writers who do nothing but build and refine documentation. Most of what developers consider to be carelessness in reading docs is really poorly written or constructed docs.
- Because of that, reading technical documentation is a skill. Remember the first time you looked at a man page? When you did that, you were probably vastly more technical than a typical end user. Technical documentation is just opaque to most users.
- Most end user focused commercial software is barely documented because it doesn’t need to be. Most end users wouldn’t even think to consult documentation, let alone know how to find documentation. Hell, even in the 90s the very first thing people threw away was the booklet that came with the CD ROM.
- FOSS developers embracing design knowledge can bring FOSS software to a commercial level of usability. That alone odd a worthy goal.
Nobody has the right to demand anything of anybody who’s volunteering their time. Never said they did. We who develop FOSS should view usability and interface concerns just as seriously as technical concerns.
Documentation doesn't suck because companies aren't using wikis right.
Documentation sucks because it's hard/impossible to do well. Every change to the code can trigger cascading changes in documentation and there's no compiler to tell you which things need to change.
I've been playing with some software over the last week that has wiki for documentation and an active user forum with people willing to help. But it's completely disordered and incredibly hard to discover. Half the battle with usability is making it easy to use and understand.
reply