Skip to main content
Software Engineering

Return to Answer

Bounty Awarded with 100 reputation awarded by Michaël Le Barbier
Explaining that I don't like teaspoons, and prefer the metric system instead. :)
Source Link
dsw88
dsw88
  • 1.8k
  • 1
  • 13
  • 14

I think you've done a very good job summarizing most types of documentation into those three categories. I would like to add two more:

Beginner Knowledge/Bootstrapping

You could classify this under Recipes, but I think it's different enough to deserve its own category. A recipe already assumes a basic knowledge of the system. Writing a recipe for food already assumes a basic knowledge of the cooking domain: You should already know what a tsp is (if you're using that strange system of measurements. :) ), how to use an oven, microwave, etc.

For someone who has never cooked or made food in their life, you'd want a gentle introduction to the entire system, showing them what they can do, and giving them little tidbits of coolness along the way to keep them interested.

The same applies to documentation. A beginner will quickly throw away a recipe book, because they don't have enough domain knowledge to even appreciate the recipes. Therefore, they need some beginner knowledge, or bootstrapping. Here's some points about this documentation format:

  • Very basic, making sure to explain every possible unfamiliar term. This can be frustrating to some users, but is essential in order to educate anyone looking at the documetentation
  • Lots of small examples to keep the user interested. These aren't recipes, per se, but they are little things to keep the beginner interested, knowing that this product does cool stuff
  • Lots of links to other places in the documentation (Recipes, Expert Knowledge, etc.) where they can learn more about some of the concepts being discussed
  • Short enough to be easily digested. No one wants to read a 300-page introductory novel

Marketing

You could argue that this isn't really "documentation", but it often gets included in documentation. These are descriptions of "why our product is so awesome that you should use it". It's a long-winded description of how the product beats the competition. This is less prevalent in open-source software, but you see it all the time in commercial software.

I think you've done a very good job summarizing most types of documentation into those three categories. I would like to add two more:

Beginner Knowledge/Bootstrapping

You could classify this under Recipes, but I think it's different enough to deserve its own category. A recipe already assumes a basic knowledge of the system. Writing a recipe for food already assumes a basic knowledge of the cooking domain: You should already know what a tsp is, how to use an oven, microwave, etc.

For someone who has never cooked or made food in their life, you'd want a gentle introduction to the entire system, showing them what they can do, and giving them little tidbits of coolness along the way to keep them interested.

The same applies to documentation. A beginner will quickly throw away a recipe book, because they don't have enough domain knowledge to even appreciate the recipes. Therefore, they need some beginner knowledge, or bootstrapping. Here's some points about this documentation format:

  • Very basic, making sure to explain every possible unfamiliar term. This can be frustrating to some users, but is essential in order to educate anyone looking at the documetentation
  • Lots of small examples to keep the user interested. These aren't recipes, per se, but they are little things to keep the beginner interested, knowing that this product does cool stuff
  • Lots of links to other places in the documentation (Recipes, Expert Knowledge, etc.) where they can learn more about some of the concepts being discussed
  • Short enough to be easily digested. No one wants to read a 300-page introductory novel

Marketing

You could argue that this isn't really "documentation", but it often gets included in documentation. These are descriptions of "why our product is so awesome that you should use it". It's a long-winded description of how the product beats the competition. This is less prevalent in open-source software, but you see it all the time in commercial software.

I think you've done a very good job summarizing most types of documentation into those three categories. I would like to add two more:

Beginner Knowledge/Bootstrapping

You could classify this under Recipes, but I think it's different enough to deserve its own category. A recipe already assumes a basic knowledge of the system. Writing a recipe for food already assumes a basic knowledge of the cooking domain: You should already know what a tsp is (if you're using that strange system of measurements. :) ), how to use an oven, microwave, etc.

For someone who has never cooked or made food in their life, you'd want a gentle introduction to the entire system, showing them what they can do, and giving them little tidbits of coolness along the way to keep them interested.

The same applies to documentation. A beginner will quickly throw away a recipe book, because they don't have enough domain knowledge to even appreciate the recipes. Therefore, they need some beginner knowledge, or bootstrapping. Here's some points about this documentation format:

  • Very basic, making sure to explain every possible unfamiliar term. This can be frustrating to some users, but is essential in order to educate anyone looking at the documetentation
  • Lots of small examples to keep the user interested. These aren't recipes, per se, but they are little things to keep the beginner interested, knowing that this product does cool stuff
  • Lots of links to other places in the documentation (Recipes, Expert Knowledge, etc.) where they can learn more about some of the concepts being discussed
  • Short enough to be easily digested. No one wants to read a 300-page introductory novel

Marketing

You could argue that this isn't really "documentation", but it often gets included in documentation. These are descriptions of "why our product is so awesome that you should use it". It's a long-winded description of how the product beats the competition. This is less prevalent in open-source software, but you see it all the time in commercial software.

Source Link
dsw88
dsw88
  • 1.8k
  • 1
  • 13
  • 14

I think you've done a very good job summarizing most types of documentation into those three categories. I would like to add two more:

Beginner Knowledge/Bootstrapping

You could classify this under Recipes, but I think it's different enough to deserve its own category. A recipe already assumes a basic knowledge of the system. Writing a recipe for food already assumes a basic knowledge of the cooking domain: You should already know what a tsp is, how to use an oven, microwave, etc.

For someone who has never cooked or made food in their life, you'd want a gentle introduction to the entire system, showing them what they can do, and giving them little tidbits of coolness along the way to keep them interested.

The same applies to documentation. A beginner will quickly throw away a recipe book, because they don't have enough domain knowledge to even appreciate the recipes. Therefore, they need some beginner knowledge, or bootstrapping. Here's some points about this documentation format:

  • Very basic, making sure to explain every possible unfamiliar term. This can be frustrating to some users, but is essential in order to educate anyone looking at the documetentation
  • Lots of small examples to keep the user interested. These aren't recipes, per se, but they are little things to keep the beginner interested, knowing that this product does cool stuff
  • Lots of links to other places in the documentation (Recipes, Expert Knowledge, etc.) where they can learn more about some of the concepts being discussed
  • Short enough to be easily digested. No one wants to read a 300-page introductory novel

Marketing

You could argue that this isn't really "documentation", but it often gets included in documentation. These are descriptions of "why our product is so awesome that you should use it". It's a long-winded description of how the product beats the competition. This is less prevalent in open-source software, but you see it all the time in commercial software.