| One often overlooked aspect of technical writing is the formatting/ease of navigation. You could have the most wonderful documentation, very clearly written, but if its navigation is a pain it will degrade the experience and frustrate the user. Just a (rather petty) example, React documentation is often lauded as very good,and I kinda agree. But if you visit from a "low" resolution laptop(1366x768) and click in advanced options to the right on this link: https://reactjs.org/docs/getting-started.html It turns out you cannot scroll the options easily by using keys or a 2-button mouse because it does not have a scroll bar (why?). You have to use the scroll-wheel(not everybody has it) or drag down the menu in a clunky way, and this is the documentation of a front-end framework. Another pet-peeve of mine it is what I call the "Netflix effect", the documentation is fine but there is not a clear, straightforward table of contents, and there are lot of internal links in the documentation so you jump from one place to the other but you are not really sure what order you are following or how much ahead or behind you are jumping from your current section. Microsoft .NET documentation is like that. On the other hand, this is a very good example(except by the annoying Discuss thing) https://javascript.info/ Everything is laid out in a very straightforward way, at any moment you have a very clear mental model of where you are in the document. Postgres, Rails and Django are a little less clear in that sense but still extremely well organized. |