1 larger project that will be a quick start for most people.
I am creating examples source code for a library that I have created.
For this question lets assume that my library has Math functions such as Add(), Sub(), Divide(), Multiple(), etc…
What would you rather see in the example folder?
10 smaller projects each showing a different feature of the library. - These examples will be small and concise. Showing only the single feature of the library, maybe with several examples of that feature The user will have to open and run each of the 10 examples to get a good idea of what the library can do before they build their own application.
1 larger project that shows all the functionality of the library - This would be a quick start application that would show all of the features of the library in a single project. The application would be the most common use-case for this library. A calculator !
I am leaning towards the single large project as it will become the base application for most other people. Then people can remove the features that they are not using.
I’m a big fan of single example and then one big composite example. For instance, if you allow for nested or cascaded functionality, like variable.Add(X).Remove(Y), then the composite example would be really helpful.
A large example, but if and only if the complete API is otherwise well documented with concise examples inline with the functional documentation. So basically, both.
I don’t want to wade through a weighty example to see general usage for a simple part of your library, but on the other hand, discrete examples often don’t cover larger, idiomatic issues regarding using the library. Anything of substance should probably have at least one “complete” example, though any non-trivial library will certainly not be entirely covered in a single example.
tl;dr: In your library’s formal API documentation, intersperse brief examples (1-10 LOC) within the function documentation, where they make sense. Slightly longer examples probably make sense in the context of a class or module document, perhaps showing idiomatic usage and giving an idea of general semantics of the library such as Ty’s example. Long-form examples are nice to see separate from these, but the former are much more important.
PS: This is highly dependent on your audience. I am constantly frustrated by documentation for “maker” products (for lack of a better term) due to their lack of formality and completeness. For the target audience though, this is probably appropriate.
A series of individual functions called by a greater whole?
I guess it depends on how you envision the library being used. Frequently I just want an example of a given function so I would say go the individual route unless they are inextricably linked
Yes; I guess I was trying to say that basically having a real world example in long form would be the best synergy to short form examples that document the separate calls.
You could potentially have the examples in your real documentation, in the way that for instance PHP documents their calls, as well as the full deal. Basically, document the dishes/ingredients (components) and then document how to actually prepare the meal/courses?
You dump a 900-line “bible” along with your API and it’s intimidating as all hell without really adding anything more than typical “language reference” pages that have like 6 lines for each function.
I agree with the call for “both”. It would be good to have a complete library to see the “big picture”, but if I want to use a specific feature, I’d like to be able to access it on it’s own, and possibly look at examples of it. In an all-in-one library, how many examples would you provide for each feature?
And I agree with what others have said: no matter which route you go, have understandable documentation for the features.
As with most development, documentation and example code is left to the end of the project and when there is not enough time to do it right. This is why projects like http://swagger.io/ or http://www.stack.nl/~dimitri/doxygen/ are so useful.
Sounds like every documentation for every 3rd party non open source project I have ever used. (not a good thing)
As I am running out of time on this project (~2 hrs left) I think the documentation with be the test cases (shutter) with a small ~300 word brief for the of the project.
Too late to matter for now, but… I think documentation can be more important than quality of your product for the successful spread of APIs and other software tools.
As a case study, consider PHP versus ASP.NET. PHP is used more often (crappy supporting chart) but it has to be one of the worst train wrecks of a language/API ever used on a production website. Now lets look at the documentation for a simple task, like say, converting to boolean: PHP provides 11 examples, where ASP.NET provides two. I’m surprised they supply even those two, although they are the most trivially obvious cases you could have. (Zero converts to false? You don’t say!)
Another case study would be MySQL, which was also better documented than much higher quality competing databases back in the day, and MySQL took off along with PHP.
