I am currently documenting a command line interface that supports CRUD (Create, Read, Update, and Delete) operations for a variety of objects.

As you can imagine, every object uses many of the same arguments. For example, when creating an object, the user can:

• Describe the object
• Activate the object
• Identify the type of data the object contains

After talking with users, I learned that they would like to be able to look up each object and find the details for the CRUD operations for that object. So, the general organization is as follows:

• Create [object]
• Read [object]
• Update [object]
• Delete [object]

[Repeat for the next object.]

With this organization comes a lot of repetitive information, and this is where conrefs are extremely useful.

I created a single page, stored in a special folder, that contains all of the reusable arguments and their explanations. Then, for each object, I can simply insert the reference to the content! This means:

• No errors (or, if there is an error, at least the same one repeats throughout the document)
• Content is easy to update. I update it in one place and it updates all of the commands.
• Content is easy to reproduce. I simply insert the conref and get the same content in each command.

Wonderful!

Have you found other benefits to using conrefs? Please share them with me if you have.