Post History
There are different types of examples and they serve different purposes. One type is the quick-start example that this answer describes: a complete, but small, runnable example packaged in a form ...
Answer
#4: Post edited
by
Monica Cellio
·
2021-06-20T20:13:58Z (almost 3 years ago)
updated link
There are different types of examples and they serve different purposes.One type is the **quick-start example** that [this answer](https://writing.stackexchange.com/a/33589/1993) describes: a complete, but small, runnable example packaged in a form that the users can easily use. "Hello world" is sometimes _too_ simple (simplistic), but this example should use defaults where possible and not bite off too much -- the user should be able to run it and understand what he's looking at without too much research. This example generally shouldn't be code in \<pre\> blocks that people have to cut and paste; attach or post the code, project files, data files, or whatever's needed alongside the doc instead.Another type is the **focused excerpt** , such as you find in API reference documentation. On the reference page about a class and its member functions, you include example invocations of those member functions in isolation. On the reference page about an interface that the user will implement, you include example implementations of key functions. These examples are not complete and runnable; you use them to demonstrate specific, focused points. This approach isn't limited to API reference pages; on my current project we excerpt published examples in the programming guides, too.Another type is the **full, realistic example**. (Or sometimes a **reference implementation**.) . As with the quick-start example, you post this code separately rather than embedding it into the documentation text (which would definitely be bloat). However, in the documentation you can provide an overview of this example -- structure, descriptions of key components, flow diagrams, class hierarchies, or whatever types of explanation make sense in your specific domain.Complete examples, whether quick-start or fuller, should contain good internal comments that focus on _why_ and _how_, not just _what_. You're writing a sort of tutorial in the comments. Your comment-to-code ratio will probably be higher than in internal code, but it needn't be _that_ much higher. Your goal is concise yet informative.
- There are different types of examples and they serve different purposes.
- One type is the **quick-start example** that [this answer](https://writing.codidact.com/posts/26400#answer-26402) describes: a complete, but small, runnable example packaged in a form that the users can easily use. "Hello world" is sometimes _too_ simple (simplistic), but this example should use defaults where possible and not bite off too much -- the user should be able to run it and understand what he's looking at without too much research. This example generally shouldn't be code in \<pre\> blocks that people have to cut and paste; attach or post the code, project files, data files, or whatever's needed alongside the doc instead.
- Another type is the **focused excerpt** , such as you find in API reference documentation. On the reference page about a class and its member functions, you include example invocations of those member functions in isolation. On the reference page about an interface that the user will implement, you include example implementations of key functions. These examples are not complete and runnable; you use them to demonstrate specific, focused points. This approach isn't limited to API reference pages; on my current project we excerpt published examples in the programming guides, too.
- Another type is the **full, realistic example**. (Or sometimes a **reference implementation**.) . As with the quick-start example, you post this code separately rather than embedding it into the documentation text (which would definitely be bloat). However, in the documentation you can provide an overview of this example -- structure, descriptions of key components, flow diagrams, class hierarchies, or whatever types of explanation make sense in your specific domain.
- Complete examples, whether quick-start or fuller, should contain good internal comments that focus on _why_ and _how_, not just _what_. You're writing a sort of tutorial in the comments. Your comment-to-code ratio will probably be higher than in internal code, but it needn't be _that_ much higher. Your goal is concise yet informative.
#3: Attribution notice added
by
System
·
2019-12-08T08:04:45Z (over 4 years ago)
Source: https://writers.stackexchange.com/a/33660 License name: CC BY-SA 3.0 License URL: https://creativecommons.org/licenses/by-sa/3.0/
#2: Initial revision
There are different types of examples and they serve different purposes. One type is the **quick-start example** that [this answer](https://writing.stackexchange.com/a/33589/1993) describes: a complete, but small, runnable example packaged in a form that the users can easily use. "Hello world" is sometimes _too_ simple (simplistic), but this example should use defaults where possible and not bite off too much -- the user should be able to run it and understand what he's looking at without too much research. This example generally shouldn't be code in \<pre\> blocks that people have to cut and paste; attach or post the code, project files, data files, or whatever's needed alongside the doc instead. Another type is the **focused excerpt** , such as you find in API reference documentation. On the reference page about a class and its member functions, you include example invocations of those member functions in isolation. On the reference page about an interface that the user will implement, you include example implementations of key functions. These examples are not complete and runnable; you use them to demonstrate specific, focused points. This approach isn't limited to API reference pages; on my current project we excerpt published examples in the programming guides, too. Another type is the **full, realistic example**. (Or sometimes a **reference implementation**.) . As with the quick-start example, you post this code separately rather than embedding it into the documentation text (which would definitely be bloat). However, in the documentation you can provide an overview of this example -- structure, descriptions of key components, flow diagrams, class hierarchies, or whatever types of explanation make sense in your specific domain. Complete examples, whether quick-start or fuller, should contain good internal comments that focus on _why_ and _how_, not just _what_. You're writing a sort of tutorial in the comments. Your comment-to-code ratio will probably be higher than in internal code, but it needn't be _that_ much higher. Your goal is concise yet informative.
#1: Imported from external source
by
System
·
2018-02-21T03:59:17Z (about 6 years ago)
Original score: 2