: 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

Vote Up Vote Down

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 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.

(0)

Vote Up Vote Down

The purpose of API documentation is to explain how to use the API. Providing sample code of how to use key features is a good way to demonstrate the intended usage.

A good example of this is the ZMQ guide. It has example code in a large number of languages to go with each of the of the concepts discussed.

They combat the bloat by displaying links to the example code in every language the library is supported in. Only when a link is clicked on is the code displayed.

(0)

Vote Up Vote Down

Working samples is an absolute must for all APIs. Period. Reference pages especially need one. Not including them overlooks the fact that API documentation is used by a range of people. It's short sighted by both the guys who says it and for the writing team to assume the documentation is only for the experienced developers. It has to appeal to both the experienced developer, the developer new to your product, and the inexperience developer. Each will divine from the suite what they need and ignore the rest.

You want to make the transition to your product as easy as possible and working, copy and paste is the best way. I'd like to see a API documentation suite using only examples. The irony is, the most experience the developer, the less they read the documentation. At that point, they really only want code to copy and paste.

"Working sample" has different meanings, though. It doesn't have to be a fully functioning WinForms application. It doesn't need to be a "Hello, World." That can be saved for the tutorial or the comprehensive sample. Instead, a working sample can be a function that if pasted into a full application, will work almost without modification. MSDN does an excellent job of this. Each of their pages has a working sample.

Don't worry about the IDE. Pick a common one and stick with that. Don't worry about bloat. We're creating reference documentation that has to be complete. We have dictionaries that they keep adding words to each year, and no one complains.

(0)

Vote Up Vote Down

I can understand the reasoning from both sides. A complete quick start is essential to ensure that the reader has sufficient information to see the product running correctly, and is able to demonstrate and present a sample default use case to the user, without these the casual reader will not know whether to bother reading further because they will be unable to understand what the product really does.

However, once you have a basic understanding of the product, the potentially lengthy quick start set-up, prerequisites and so on is merely bloat compared to the reader getting down to the information they really need.

The answer here is to hive the quick start into a separate section or document, and offer sample code either as part of your product or available in an online hosted repository such as GitHub. This would mean that the full set up details could be left in the README for example, and the quick start in the API reference could be reduced to Download the code and follow the instructions

Compare and contrast the following level of detail on the Java Date-Time API

Overview: docs.oracle.com/javase/tutorial/datetime/overview/design.html API Reference: docs.oracle.com/javase/8/docs/api/java/time/package-summary.html Demo Code: github.com/sualeh/java8-timeapi-examples

The first two would be found within your reference documentation, the third one would be a link to avoid bloat.

The audience may well be experienced developers, but they will not have full understanding of your product, and trust me they will appreciate having a Hello World.

(0)

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)