|
I find this troublesome because it attempts to categorize documentation in a synthetic way and then stops. While that's totally fine and a field on its own, this is not how people learn. It's akin as to saying that to learn French you need to categorize words as "substantives", "adjectives", "verbs", etc. Sure it's slightly useful, but it's just not how people approach learning. Instead, and I mean to eventually write this long-form, I find it a lot more useful to think of documentation as a learning experience. You need several levels: for those who don't even know they want to learn it, for the beginners, for the seasoned that need a quick ref, for the ones who just lack practice, etc. In this way, tutorials will cater for a specific type of learners while the API docs will be a reference for those with already experience. That is why I will also argue that library authors tend to go to the API docs. I read the docs of my own libraries, so while I have a feeling how it works I might want to quickly check the format of e.g. the second options argument. Since I wrote it, it's very useful for me to document the API since I already know how to get started or why to even use it. But that's not the same for others. So I will argue that from the landing page (if any) to the API docs, there's no a strong divide and you should start teaching the user from the beginning. As an example, my projects tend to include a few-lines snippet as soon as possible. PS, to do great documentation is a full-time job, and I still maintain that some ideal-ish ratio of lines of code vs testing vs documentation, given all the time in the world to work on it, is 1:5:10. as in, for each 1 line of code there should be 10 lines/paragraphs of documentation. |