: Re: What are the benefits of including complete working code samples in documentation When documenting software API so others know how to access the various methods, what data structures are used

@Karen856

Vote Up Vote Down

The value of adding code examples to documentation depends on the example itself as well as the API or library in question. I work with a widely used software library, and we have a stated expectation that our users are well beyond the "Hello, World!" level. We have examples and guides that build components incrementally, where each part is self contained and working, where the end result is fully working applications.

Self-contained code examples show ways to achieve explicit end goals. It (hopefully) helps the reader to write better and more efficient code. It serves as inspiration, nurturing ideas about how to do things easier, smarter, quicker, more elegant.

With regards to the grounds for rejection you're describing:

A tutorial may be tied to a specific IDE in that it uses one, but the code in question should at the very least be able to compile and run on the platform used in the tutorial. The source code itself could be written in your favorite text editor, there's no need for an IDE for relatively simple projects.
A fully working code sample can (and should!) be way more advanced than "Hello world". Even experienced developers learn from reading code, maybe even more so than beginners. This applies particularly to intermediate level developers.
If it bloats the documentation, it should be rewritten, improved, or removed - regardless of whether or not it contains a code sample.

(0)

Login to post a comment!