: 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

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.

Load Full (0)

: How to describe the concept of 'humanity' when dealing with non-human characters I'm dealing with a group of non-human characters and Character A is reflecting on how he knows Character B is

@Sarah872

Load Full 1 Comments

: Should I write about a particular lingering thought? I have had the thought of writing about a nation with states on another planet. The planet is earth-like and the quantity of some resources

@Sarah872

Load Full 2 Comments

: Presenting unrelated or vaguely-related stories in a setting in backwards chronological order by epoch? I'm thinking of a science-fiction or science-fantasy setting wherein modern humanity colonizes

@Sarah872

Load Full 4 Comments

: It may or may not be true that every crisis in the real world is an opportunity, but it is true that every writing challenge is a writing opportunity. The challenge of multiple language

: 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

More posts by @Sarah872

: How to describe the concept of 'humanity' when dealing with non-human characters I'm dealing with a group of non-human characters and Character A is reflecting on how he knows Character B is

: Should I write about a particular lingering thought? I have had the thought of writing about a nation with states on another planet. The planet is earth-like and the quantity of some resources

: Presenting unrelated or vaguely-related stories in a setting in backwards chronological order by epoch? I'm thinking of a science-fiction or science-fantasy setting wherein modern humanity colonizes

: It may or may not be true that every crisis in the real world is an opportunity, but it is true that every writing challenge is a writing opportunity. The challenge of multiple language

Login to post a comment!

0 Comments

Back to top