Documenting style : Narrative vs. Hybrid style ( Narrative + compact or list based )

There are a couple of style in writing technical documentation. In 80’s and 90’s, it looked to me actual S/W engineers wrote books and document on technical issues. So, at that time, it was full of source code and more compact but easy-to-look-up-later style.

However, somehow from late 90’s, technical document/books became very lengthy and narrative.
So, you should read from the first line to the last line carefully not to miss information. This can be good at first, but let’s say that you already know those information but have to revisit it because you want to make sure some details or you forgot detailed information although you know and remember overall procedure. Then, it slows down things. It’s kind of irritating.

Let’s take one example from Apple’s document.

Providing the Data to the Table View
You must provide data to the table view. This can be done using one of two methods: programmatically by implementing a datasource class or by establishing a relationship between the table view and a controller using Cocoa bindings.

When providing data programmatically you create a class that conforms to the NSTableViewDataSource protocol and implement the method that provides the row and column data as requested. Content can simply be displayed and, when appropriate, can also be edited.

You can also provide content to a table view using Cocoa bindings. Bindings allows you to create a relationship between a controller class instance, which manages the interaction between data objects and the table view. The bindings approach allows you to bypass the datasource class for providing the data as well as supporting editing of the data.

Because the techniques for view-based cell creation and populating and cell-based table view populating and editing are quite different these chapters have been separated by topic.

That’s very narrative. Maybe good for novel, but not technical document. Technical document should allow readers to catch information quickly and thus construct overall idea easily. How about this?

Providing the Data to the Table View
You must provide data to the table view. This can be done using one of two methods:

  • programmatically by implementing a datasource class
  • by establishing a relationship between the table view and a controller using Cocoa bindings.

When providing data programmatically you create a class that conforms to the NSTableViewDataSource protocol and implement the method that provides the row and column data as requested. Content can simply be displayed and, when appropriate, can also be edited.

You can also provide content to a table view using Cocoa bindings. Bindings allows you to create a relationship between a controller class instance, which manages the interaction between data objects and the table view. The bindings approach allows you to bypass the datasource class for providing the data as well as supporting editing of the data.

Because the techniques for view-based cell creation and populating and cell-based table view populating and editing are quite different these chapters have been separated by topic.

Or how about this?

Providing the Data to the Table View
You must provide data to the table view. This can be done using one of two methods:

  • programmatically by implementing a datasource class

You create a class that conforms to the NSTableViewDataSource protocol and implement the method that provides the row and column data as requested. Content can simply be displayed and, when appropriate, can also be edited.

  • by establishing a relationship between the table view and a controller using Cocoa bindings.

You can also provide content to a table view using Cocoa bindings. Bindings allows you to create a relationship between a controller class instance, which manages the interaction between data objects and the table view. The bindings approach allows you to bypass the datasource class for providing the data as well as supporting editing of the data.

Because the techniques for view-based cell creation and populating and cell-based table view populating and editing are quite different these chapters have been separated by topic.

 

The first style with a bullet list is better to grab the fact that there are two ways to achieve it. And when you revisit this issue later, you can quickly catch the idea and refresh your memory more easily. However, when you want to read explanation on those especially for what kind of detailed differences there are, the 1st one still fails. So, the 2nd one is better.

What do you think about it?

Leave a Reply

Please log in using one of these methods to post your comment:

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

%d bloggers like this: