August 2023 Summaries

The principle of DRY (Don't Repeat Yourself) is a fundamental concept in software development that helps maintain clean and efficient code by avoiding redundancy. However, applying this principle to technical documentation can sometimes be counterproductive. While DRY can make code easier to maintain and less buggy, it may create unnecessary friction for users trying to learn from the documentation. In some cases, repeating information in documentation (RYL - Repeat Yourself Liberally) can improve user experience by making essential information more accessible and reducing the need for constant navigation between different sections of the documentation. This approach is particularly useful in tutorials that aggregate information from various sources or when explaining non-intuitive behavior that may cause user frustration. Ultimately, striking a balance between DRY and RYL principles in technical documentation depends on the specific context and requirements of the project. It's essential to prioritize user experience and ensure that users can easily find the information they need without being overwhelmed by excessive repetition or forced to navigate through complex documentation structures.

The principle of DRY (Don't Repeat Yourself), while beneficial in software development for maintaining and testing code quality, can be counterproductive when applied to documentation. The EdgeDB documentation serves as an example, illustrating that repeated information, such as installation instructions, ensures ease of access and usability for users, rather than forcing them to navigate multiple links. This approach, referred to as RYL (Repeat Yourself Liberally), acknowledges that while some redundancy is necessary, especially in tutorials and contexts where information aggregation is crucial, it prevents users from having to piece together fragmented information from various sources. The balance between DRY and RYL depends on the context, as certain elements like CLI connection flags may be better served through DRY to avoid unnecessary duplication. Ultimately, the goal is to support users effectively by providing them with the information they need in a straightforward manner, recognizing that what works for software code might not translate well to user-facing documentation.