What are Edgy Docs?
Doc Edge is all about producing Edgy Docs. Edgy Docs give your product an advantage over other products, while pushing beyond the standards and limitations of traditional documentation.
Throughout the life of the Doc Edge blog, we will talk a lot about what goes into Edgy Docs, and give plenty of examples. For now, I will briefly discuss some of the basic characteristics that Edgy Docs should exhibit. Some of these qualities relate to each other, and some would not be possible without the others. (Not all great docs will exhibit all of these qualities, but the perfect doc would incorporate these, and perhaps some other qualities, flawlessly.)
Edgy Docs are:
Structured -- Structured docs define themselves. They make it easy to search for data, reuse data, and stylize data based on context. Most document structuring is done using XML. Structured docs open the way for non-book, non-help based forms of documentation. Docs integrated with the application, that allow people to explore the UI and learn from the docs at the same time. Structured docs lead to improved maintenance, better issue tracking, and a more consistent look and feel across a product's documentation set.
Swift -- Swift docs can be produced, delivered, and updated quickly. Swift docs make use of automation, reuse, and single sourcing. Swift docs are never out of date and can be printed on demand. If you are writing a Swift doc, you are doing so in an Agile environment, without specs, and you are considering all possible options to add value to the product; you are not assuming that the best you can do is fill a PDF with words. Swift is not just about how the doc is produced and maintained, it is also about how the user interacts with the doc.
Smart -- Smart docs leverage the collective knowledge of all the disciplines related to communicating information. Information design, graphic design, the teaching profession, web site design, usability, journalism, and so on. Smart docs also have an awareness of the user and his or her needs. Smart docs may suggest answers, point users in the right direction, or do something special to help the user remember something they have forgotten in the past. The smarter docs get, the more they become learning tools and applications.
Shared -- Everyone has access to Shared docs, and everyone has the ability to customize or create their own Shared docs - even customers. Shared docs contain all the knowledge about a particular product. Shared docs allow for online review and editing, even after the doc has been released. Shared docs create opportunities for users to be active participants in the documentation feedback loop and to customize the documentation for their own needs and perhaps add something that the original author didn't anticipate was necessary (or even know was available). Finally, shared docs can be shared with everybody across the globe. Mutliple languages and character encodings are supported through the use of translation-aware authoring and standards-based authoring tools.
Saleable -- Saleable docs impact the bottom line. At the very least, they are so Structured, Swift, Smart, and Shared that they save money. But, more importantly, the make money. Saleable docs can make money in one of two ways. First, documentation will become a major differentiator in the globalized, advancing world as more and more things become commoditized. For this reason, it is important to have a reputation as a producer of quality documentation that users can and do read, thus making them more productive in their real jobs. Secondly, Edgy Docs can actually create revenue. Because people want to read Edgy Docs, they are willing to pay for them as a useful service, perhaps subscribe to them, or even buy them from a third party publisher who licenses the information. As the age of open source software rolls on, software companies may one day be giving away all the software and making a good portion of their money on the documentation, or at least parts of it.
So, there they are. The 5 S's of Edgy Docs. Until we come up with another S, all of the ideas and documents discussed on Doc Edge will relate to one of these 5 categories. If you've got any other ideas, please send them along.
Throughout the life of the Doc Edge blog, we will talk a lot about what goes into Edgy Docs, and give plenty of examples. For now, I will briefly discuss some of the basic characteristics that Edgy Docs should exhibit. Some of these qualities relate to each other, and some would not be possible without the others. (Not all great docs will exhibit all of these qualities, but the perfect doc would incorporate these, and perhaps some other qualities, flawlessly.)
Edgy Docs are:
Structured -- Structured docs define themselves. They make it easy to search for data, reuse data, and stylize data based on context. Most document structuring is done using XML. Structured docs open the way for non-book, non-help based forms of documentation. Docs integrated with the application, that allow people to explore the UI and learn from the docs at the same time. Structured docs lead to improved maintenance, better issue tracking, and a more consistent look and feel across a product's documentation set.
Swift -- Swift docs can be produced, delivered, and updated quickly. Swift docs make use of automation, reuse, and single sourcing. Swift docs are never out of date and can be printed on demand. If you are writing a Swift doc, you are doing so in an Agile environment, without specs, and you are considering all possible options to add value to the product; you are not assuming that the best you can do is fill a PDF with words. Swift is not just about how the doc is produced and maintained, it is also about how the user interacts with the doc.
Smart -- Smart docs leverage the collective knowledge of all the disciplines related to communicating information. Information design, graphic design, the teaching profession, web site design, usability, journalism, and so on. Smart docs also have an awareness of the user and his or her needs. Smart docs may suggest answers, point users in the right direction, or do something special to help the user remember something they have forgotten in the past. The smarter docs get, the more they become learning tools and applications.
Shared -- Everyone has access to Shared docs, and everyone has the ability to customize or create their own Shared docs - even customers. Shared docs contain all the knowledge about a particular product. Shared docs allow for online review and editing, even after the doc has been released. Shared docs create opportunities for users to be active participants in the documentation feedback loop and to customize the documentation for their own needs and perhaps add something that the original author didn't anticipate was necessary (or even know was available). Finally, shared docs can be shared with everybody across the globe. Mutliple languages and character encodings are supported through the use of translation-aware authoring and standards-based authoring tools.
Saleable -- Saleable docs impact the bottom line. At the very least, they are so Structured, Swift, Smart, and Shared that they save money. But, more importantly, the make money. Saleable docs can make money in one of two ways. First, documentation will become a major differentiator in the globalized, advancing world as more and more things become commoditized. For this reason, it is important to have a reputation as a producer of quality documentation that users can and do read, thus making them more productive in their real jobs. Secondly, Edgy Docs can actually create revenue. Because people want to read Edgy Docs, they are willing to pay for them as a useful service, perhaps subscribe to them, or even buy them from a third party publisher who licenses the information. As the age of open source software rolls on, software companies may one day be giving away all the software and making a good portion of their money on the documentation, or at least parts of it.
So, there they are. The 5 S's of Edgy Docs. Until we come up with another S, all of the ideas and documents discussed on Doc Edge will relate to one of these 5 categories. If you've got any other ideas, please send them along.
posted by Pete at 6:26 PM
0 Comments:
Post a Comment
<< Home