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 etc, I like to document each bit in detail and also include, regardless of the coding language, a "hello world" style sample API client that shows how a few select methods and data items can be used for simple, life-like purposes. My argument is that first-time users can get started more easily and delve into the API services more quickly. However, from developers, I often get a rejection when I ask for a complete working code sample on various grounds:
- It would be IDE specific so it would not help people who use a different IDE.
- The audience is experienced developers who need no "hello world" to get started.
- It makes the document way too bloated and adds very little value.
So my question is, what is the added value, if any, of including simple, fully working code samples in API guides.
This post was sourced from https://writers.stackexchange.com/q/33587. It is licensed under CC BY-SA 3.0.
4 answers
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 comment threads
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.
This post was sourced from https://writers.stackexchange.com/a/33590. It is licensed under CC BY-SA 3.0.
0 comment threads
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.
This post was sourced from https://writers.stackexchange.com/a/33591. It is licensed under CC BY-SA 3.0.
0 comment threads
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: https://docs.oracle.com/javase/tutorial/datetime/overview/design.html
- API Reference: https://docs.oracle.com/javase/8/docs/api/java/time/package-summary.html
- Demo Code: https://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.
This post was sourced from https://writers.stackexchange.com/a/33589. It is licensed under CC BY-SA 3.0.
0 comment threads
0 comment threads