Post History

Source: https://writers.stackexchange.com/a/34682
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

Source: https://writers.stackexchange.com/a/34682
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

Theoretical concepts are always difficult to understand without examples. Plus, the examples can provide evidence of the soundness of the concepts and generally increase the reader's confidence both in their understanding of the concepts and in the soundness of the concepts themselves.

So yes, including examples in you conceptual material is a good idea. If the concept you are explaining is complex or unfamiliar, it is also good to build it up in layers with examples for each layer as you introduce it. An example that is built up piece by piece from simpler parts is usually easier to comprehend than one that is presented as a single entity with all of its complexity. It is very easy to overestimate the clarity of concepts we are familiar with, so breaking it down into pieces and explaining and illustrating each piece is a good thing, even if it seems unnecessarily slow to you.

Finally, consider whether it might be better to show your examples in pseudocode rather than actual code. Not only does this avoid issues with some readers not being familiar with the language of the code, but pseudocode can be written to highlight the concept you are explaining while avoiding bits of technical complexity not relevant to the point at hand.

Original score: 4