Documentation isn’t the best place to be DRY

https://www.edgedb.com/blog/make-your-users-happy-by-keeping-it-ryl-in-documentation

by jameskerr • 3 years ago

5 2 3 years ago

This is actually an area to improve: documentation should be DRY as-written, just not as read. Repeating documentation is all good until you have to change something, and forget to change all instances. The author even mentions:

What happens if the person updating it doesn’t know to look for these additional instances? Then, three instances don’t get updated and end up leading someone in the wrong direction

but then seems to "resolve" this with

Only because the alternative is worse.

What about the third option: documentation with inlined references that expand to what they reference? This presents its own set of problems: setting up these references takes extra effort, and many developers may simply end up repeating themselves. But with the help of a smart IDE or documentation editor and some good tools (maybe even AI which can identify similar sentences), in particular an editor which lets you edit an instance anywhere rather than always having to jump to the original source, maybe we can write documentation which isn't overly terse and stays accurate.

jameskerr• 3 years ago

I think it’s easy to change a few duplicated instances. It just depends on how often they change. Once a year? Easy. Once a week? Not fun.

Documentation isn’t the best place to be DRY

Related Stories