On the Importance of Naming and Describing Features


A true story




NOTE: Names and details have been changed. However, I assure you the following conversation did occur. For the curious: I was Akuma, not Ryu.




Ryu produced a list of all the features in the product. Akuma scanned the list and found this item:




Feature 25: Context-sensitive data in event records




They spoke:




Akuma: What does “Context-sensitive data in event records”mean?




Ryu: Event records contain data that is context sensitive.




Akuma: Hmmm. What does that mean?




Ryu: When the code logs an event it puts information in the event log that provides context about the event.




Akuma: Yes, but that does that mean to our customer?




Ryu: Whenever the code does something it records the full context of what it did and stores it as part of the event log message…




Akuma: but how is that important to our users? Why do they care?




Ryu: They get the full context available when the event was generated …




This pattern repeated for 20 minutes. And then …




Akuma: So, what you are saying is: when we write something to the event log we are going to make what we write very informative so that the message makes sense to a user who reads our events?




Ryu: Yes




Akuma: So the feature is “Easy-to-read & Informative event log messages”




Ryu: Yes!




Akuma: Why didn’t you just write that in the first place?






This happens all the time




I read many “feature lists” for products. Often, I encounter them in internal documents during review meetings and planning meetings. Of course, as a consumer I encounter them on product packaging and product documentation.




Often, especially for internal documents, these lists are full of items like “Context-sensitive data in event records”. These items may be specific, technically accurate, etc. But they mean nothing.



And folks, I am always highly skeptical of someone who cannot simply explain what it is they are doing and why.




Features have to mean *something*




If you can’t crisply write a description of a feature that captures what it is and why it is valuable, you probably don’t have a clue what you are doing or why you are doing it.




The easy way to do this correctly




Features should represent value to your customer (or whoever is going to use what you are building).




If the item does not represent value to your customer, then it is very likely not a feature.




Features are not the same as Workitems




A workitem is what someone has to do. A feature is a capability of the product that has value to the end user. Features generally have one or more workitems (for developers, etc.) that implement the feature.







  • Feature: Easily recover accidentally deleted pictures
  • Workitem: File / Undelete menu item
  • Workitem: Recover Deleted File Dialog




NOTE: there are workitems that don’t support any feature. For example, performance is usually not considered a feature, but there are often many performance workitems for any product.




Not all features are Fun




Some features, products have to have. They aren’t fun to describe or implement and even the users may not care unless you do something horribly wrong, but the can take up a lot of time and effort.




The best example: “Easily install the the product”.




Yes, all our products must be installable. Few people enjoy working on this part of the product and the end users really will rarely say anything good about. However, if you disappointed the user, they will hate you for it.




An example of a well-described feature




Adobe Bridge


I’ve never even used this product. But I understand the benefit of this feature below that I found on the Adobe website.




“Scripting support


Automate labor-intensive tasks across components of the suite by writing JavaScripts or using included workflow script examples, and then store your scripts in a central location for easy access or to share with colleagues.”




I get it: this feature will save people time and help them work together. That sounds good!






Saveen Reddy



Comments (0)

Skip to main content