I mean maybe I'm just fussy, but if there isn't an authoritative reference for everything the component is intended to do, and how it will respond, how can I reasonably rely on it for anything other than trivial one-offs? I'm not saying I'm always going to read such a doc, but it's a real step into the dark to use a tool without the assurance there will be a way to answer the inevitable questions that arise later.
In many libraries I feel what's missing is the "whys" ... I want to know not just HOW to do something with the library, but WHY it's done this way and not some other way. What are the design principles? What are the design goals? Why was the library initially created, and what is its history? What design patterns do the authors prefer? Which classes are the most important, and how do all the classes fit together? In what way is this library better and worse than competitors/alternatives? And how about a few nice diagrams showing class relationships?
Wollen Sie ganz einfach Ihre eigene Homepage erstellen, ohne HTML-Kenntnisse, einfach, professionell und mit viel Freude? Probieren Sie unser Desktop Content Management System (CMS) Zeta Producer für Windows aus. Komplett mit eigenem Shop, Gästebuch, Weblog, Bildergalerien, Integration von YouTube-Videos. Wir haben eine aktive Anwender-Community, schnellen Support, sympathische Support-Mitarbeiter.
The survey misses an option: "Licensing conditions must be acceptable". It's not good if I have the perfect library but it does not fit my licensing requirements (such as a GPL library when my program shall be sold).
When learning Umbraco, I had my employer pay for access to instructional videos. They were difficult to stay awake through (I never drank coffee before them), but were the most valuable learning resource I came across.
I think it depends on the third party component. Umbraco is a whole CMS, so there were configuration files, a backend system, integration with ASP.net components, and an API, so all those moving parts could be hard to understand without explicitly seeing how they all fit together. That was why videos were useful.
For a simple API, I'd prefer articles with code samples. Also, meaningful and up to date documentation is nice. One of the annoying things about Umbraco is that there is no documentation, and many of the online resources (e.g., questions answered by experts) were out of date because of the breaking changes introduced by the more recent versions. That makes it much harder to use.
I find that videos are used more and more by organizations that don't want to write doc. Problem with video is that it is hard to skim or to work with them out out of order. You have to watch a video at the speed and the order that they are presented.
I hate videos as a way to present software APIs and I systematically avoid organizations that use them for such. Written documentation allows you to understand the API far faster than a video can.
You have to watch a video at the speed and the order that they are presented.
Probably why I was falling asleep while I was watching them.
I hate videos as a way to present software APIs
Yeah, for API's, I prefer documentation and sample code, especially in the form of tutorials based on common usage scenarios. Videos have their uses though (e.g., in complex scenarios that don't just involve coding).
It depends on the discovery of the library. If I am forced to use it (i.e. it is already integrated into my newly inherited system), then it is nice to have full API documentation.
The reason being is the system itself is the examples and the previous developers of the system 'hopefully' left documentation (articles).
If however, I am researching on a new tools I want to see some good articles, examples, and a high level summary are ideal. Seeing a over sized API or all of the source code is worthless as I have no idea where to even start or if it contains what I need.
But then again the question was "When learning to use a third party component". Maybe we are to assume we know already that we must use it (which should never be the case)
Computers have been intelligent for a long time now. It just so happens that the program writers are about as effective as a room full of monkeys trying to crank out a copy of Hamlet.
I don't know if anyone else hosts CodePlex projects, but one of the things that is very frustrating is that you can have a rich set of Xml comments in code but there is no way to publish this to codeplex - it would be great if MS and others who offer project hosting could focus more on enabling devs to document their work.
It's a cood idea, but not the most practical (IMHO) thing to do. There are already dozens of doxygen-like apps out there for most major languages, they would have to figure out how to provide integration support for them. Since CodePlex/Google Project/etc work on versioned code, documentation depends on the version of the code. If it's a real-time process of publishing, the server would have to have some smart processing and updating of the project's source files (I'm sure they don't want to waste any CPU to rebuilding the entire doc set on every commit). Then there's the issue of older/experimental versions (ie, older or other branches), should those still be published as well? Etc
Great! I voted 1 for "Pure source code examples of how to use it", meaning that it is most important SDK component. I think that I am not alone. So, the question is vague, and voting results look like handled by smoothing filter.
by it's documentation and it's support, both phone and online. This is not all that I look for but it is one of the first items on my checklist.
Just along for the ride.
"the meat from that butcher is just the dogs danglies, absolutely amazing cuts of beef." - DaveAuld (2011) "No, that is just the earthly manifestation of the Great God Retardon." - Nagy Vilmos (2011)
"It is the celestial scrotum of good luck!" - Nagy Vilmos (2011)
No matter how well a third party tool is documented there will be a time when I get stuck. At that point it is more important than anything else that I can get support from the company that made the tool or any other website that knows what they're talking about. I (and any other user) also might need updates that fix bugs, but don't break public API's. Had that once and I needed to exclude a couple of files to make it work again. I had been working for days on those files...
As for the question, from top to bottom I rate their importancy 5, 4, 3, 2, 1. Support is right up their with detailed documentation
Dig into thousands of thousands lines of source code just because there is no proper documentation? Thank you very much. No docs is no API, for me -- unless the functionality is obvious but then I don't need a source code either.
I used to think that source code was required too. Then I got what I wished for. The source code that was delivered didn't have any comments and was mildly obfuscated. So I'm not such a source code fan anymore.
Last Visit: 31-Dec-99 18:00 Last Update: 31-May-16 6:36