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

I talk in terms of an even simpler mental model that you might call the "Two-document model". All documentation really fits into two groups - "Reference level" documentation and "Guide level" documentation.

Reference level would be any API references, function explanations, data types, protocol specifications etc.. Guide level includes tutorials, conceptual explanations, how to guides, examples.

I find this to be a useful way of talking to people who need to produce some reasonable amount of documentation for something they're developing (or maybe some bare useful minimum). Often they will just write an API reference and think that they're done. By talking about "reference" and "guide" you can easily make it clear that they've got reference (kind of) covered, but they're missing and guides for how to get the SW built and then examples of how to use it.



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

Search: