6 ms·
Some thoughts on documentation: 1. Don't do things in your examples which you consider anti-patterns. A few years back I remember some Angular 1.x docs which s
by TheAceOfHearts 8y ago
Some thoughts on documentation:
1. Don't do things in your examples which you consider anti-patterns. A few years back I remember some Angular 1.x docs which showcased certain examples which the authors considered anti-patterns. Why are you surprised that users are doing things the wrong way if you're the one that taught them? If you must provide an anti-pattern examples for the sake of brevity at least note it near the code sample and explain what the correct usage should be.
2. Give examples of what certain features or options could be used for. I sometimes encounter libraries which provide weird options or methods for which I never understand their purpose. If you added the option it means you must've thought of some use-case for it, right? It's pretty useful when you're not familiarized with a domain and you want to build up the knowledge of its use-cases in case you have to deal with related problems later on.
3. If something is deprecated or its usage is discouraged be sure to point users to the proper solution. I've encountered warning blocks on MDN which suggest using a certain API, but when you click through it turns out that it's deprecated and they tell you that you shouldn't use it. Contradictory information is incredibly frustrating.
- blattimwind 8y ago> Some thoughts on documentation: Complete, syntactically correct sentences that make sense. Paragraphs / sections that have a start and an ending. Clear, concise and consistent language (part of the "7 Cs of communication that actually works"). Documentation is not a poem-writing contest. Do not substitute pseudo-synonyms (e.g. table, relation, schema), that's inconsistent and confusing. Explain concepts and define key terms. A glossary tends to be immensely helpful, especially if it links back to detailled explanations of home-grown terms. And the usual basics, e.g. think about the intended audience (what can you expect them to know, what do they want, then give them that).
- Sean1708 8y ago> I sometimes encounter libraries which provide weird options or methods for which I never understand their purpose. I won't name and shame the author because it's just a little personal project, but my favourite example of this is the following bit of documentation: get :: JSON → JSON → JSON Get the value at k from the object While I can use common sense to guess at the order, I have absolutely no idea how you're supposed to index JSON with JSON.
- Arnavion 8y agoProbably the index can be either a JSON number (for indexing arrays) or a string (for indexing objects), so it takes JSON to support both. Maybe the library also allows you to index with other JSON values and stringifies them internally, reducing them to the string case.
- voltagex_ 8y agoSubmit a bug report - treat documentation like code in that sense. You're probably not the only one confused by this.
- bowlich 8y agoNumber 1 seems to be a pattern that I see coming out of text books where the author begins the chapter by giving you an anti-pattern or okay solution to a working problem and then through the course of the chapter introduces the reader to a better solution. It's a pattern that I've always found frustrating since rarely would the "incorrect" solution have occurred to me if the author hadn't suggested it.