Why conrefs are wonderful

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.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s