Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

> if the documentation is not good enough, people will not use it.

Counterexamples: people use operating systems, web browsers, various "productivity apps" and games without reading a shred of documentation.



Is that completely true, though? Almost all modern games include a (sometimes optional) tutorial, explaining the basics of how to play the game. Some number (a few? many? most?) of productivity apps will have in-app tutorials to get you up and running. Operating Systems... might have a tutorial? It's been a while sine I booted one up, and I'd likely skip it if present.

On top of that, the GUI nature of these apps makes it easier to get started, I think, and even if there are _no_ tutorials, you can use your previous knowledge of similar apps and play around to understand it - click buttons, tap menus, etc, and learn by doing.

I'm not sure where this fits into the documentation quadrant, but it's important, and is _why_ users can get away without reading documentation.


When Windows was new, Microsoft was militant about everybody sticking to the common controls. They wanted people to get used to how they operated, so that they would be able to instantly operate a new app for the first time.


Kubernetes... (although the documentation has gotten better over the years, to the project’s credit)

Ruby on Rails as well, for the first few years of its existence.


I always found Kubernetes API reference very useful.


Yeah, that part was always fine, but they sorely lacked a theory of operations -- which is essential for any sort of state machine or orchestrator! -- and basic "man page"-type documentation around processes, config files, etc.


API's and programming languages are indeed very difficult to use effectively without documentation.

They are also not operating system user interfaces, productivity tools, games or web-browsers, and so not the topic of my little sub-thread here.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: