Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

Post History

66%
+2 −0
Q&A Does DRY (Don't Repeat Yourself) Apply to Documentation?

I would say that most of the time it does not apply. Suppose you are to document the use of one particular function. Good source code documentation instantly tells the user how to use that one fun...

posted 3y ago by Lundin‭

Answer
#1: Initial revision by user avatar Lundin‭ · 2021-02-10T14:29:27Z (over 3 years ago)
I would say that most of the time it does _not_ apply. 

Suppose you are to document the use of one particular function. Good source code documentation instantly tells the user how to use that one function. 

Now suppose a nearly identical function with nearly identical use exists. Bad documentation says "it works just like function x except..." and then sends the reader chasing the documentation of some other function that they aren't even using. Good documentation shouldn't force the reader to go look for information in multiple places in order to piece together the complete documented use.

---

To make an example of extremely bad documentation, take for example the C language ISO 9899 standard where we want to look up a very commonly used feature called "operator precedence". All it says is this:

> The grouping of operators and operands is indicated by the syntax. 85)

Without any of the mentioned syntax listed. We are instead first sent to read a cryptic foot note 85), which in turn tells us to go read the syntax in each and every sub-chapter, a total of 17 chapters. The information we need is literally scattered in 17 different places of the document. 

While they could just have summarized it with a simple table similar to [this](https://i.stack.imgur.com/XgKf8.png). Does this repeat what is said in each of the 17 chapters? Yes. But with the aid of such a table we now have useful documentation instead of utter crap. 

_Do_ repeat yourself in the form of a summary, please! 

---

Depending on what you mean to document however, you could perhaps be smart about it and place all documentation of nearly identical functions in the same place. One example is [man strcmp](https://linux.die.net/man/3/strcmp) from the Unix manual, which lists the documentation for two similar functions `strcmp` and `strncmp` in the very same place. And now they suddenly get away with writing

> The `strncmp()` function is similar, except...

because all the information is easily found in one place, on that page the user is already reading.