4 ms·
> Brevity. Assume your users are intermediate developers and only tell them what they need to know. Sorry for an interjection. The documentation I am having in
by jnxx 7y ago
> Brevity. Assume your users are intermediate developers and only tell them what they need to know.
Sorry for an interjection. The documentation I am having in mind is technical documentation for future developers of a code base (its implementation). Not users of the API a code base.
Also, it would be possible to document the wrong stuff or stuff that people really already know, but it is basically not possible to document too much, because of the time constraint.
- jackcodes 7y agoApologies for this, I’ve clarified this in my edit. I’d realised immediately after I’d submitted that it’s for a different purpose. Hope the edit clears it up a bit more.
- jnxx 7y agoBrevity is clearly an important quality aspect for all writing. But it does not come for free. For many people, writing concise documents is rather time-consuming, and there are certainly cases where you'd rather want to have a document at all, even if it is painfully bloated, than nothing.
- jackcodes 7y agoI agree, and one of the examples is your use case - undocumented enterprise software. To go back to the title, brevity makes the documentation good, but I’d rather have bloated in-date documentation than no documentation.