Audience
Concept
DRY is a common software engineering principle that we tend to try to translate into documentation, but it doesn’t pan out. Instead, keep your documentation RYL (repeat yourself liberally). It’s slightly harder to maintain, but it’s easier for your user which is the goal of documentation to begin with.
Points
Sometimes, users need to put together several distinct but related ideas in order to learn to do a single thing with your product. RYL allows them to get all (or most) of those ideas in one place, making it easier for them to succeed. DRY trades easy-for-them for easy-for-you. When you keep software DRY, you trade having to search for and change all the instances of a piece of code for having a more modular architecture that forces you to deal with a lot more different files when you want to refactor or add features. When you try to do the same with documentation, you trade the user’s time for your convenience by forcing them to bounce around your documentation for the information they need in the interest of making maintaining the documentation easier. Do the hard work of maintaining repetition to make it easy on your users
Examples
I don’t have these identified yet, but we will show examples from our own documentation. We will show instances where:
- RYL is worth it for the users
- RYL might be too much and cross-linking related content would be better
- (maybe) whether to RYL is not clear — you could make an argument for going in either direction