|
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.
|
|
|
|
|
haha
~ [Don't] Visual[ize the] Basic[s], C#[ly instead]
~ ASPX: Apple Simply Performs eXcellently
|
|
|
|
|
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?
|
|
|
|
|
I kept falling asleep trying to read through all that stuff.
| "The difference between genius and stupidity is that genius has its limits." - Albert Einstein | | "As far as we know, our computer has never had an undetected error." - Weisert | | "If you are searching for perfection in others, then you seek disappointment. If you are seek perfection in yourself, then you will find failure." - Balboos HaGadol Mar 2010 |
|
|
|
|
|
That's what TL;DR is for.
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 using a third party component..." is the key phrase. It is assumed the "third party component" has already been picked and is set for production use by those who are taking this survey.
|
|
|
|
|
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.
When it comes to pay the rent no matter what [...] I just blew a tranny [...] you do what you gotta do.
|
|
|
|
|
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.
|
|
|
|
|
sellinger wrote: 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.
sellinger wrote: 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).
When it comes to pay the rent no matter what [...] I just blew a tranny [...] you do what you gotta do.
|
|
|
|
|
I concur, that and lack of indexability make video a bad choice for imparting information. Very occasionally I come across an exception, such as Crockford's excellent "JavaScript - The Good Bits" video, but they're an exception, not the rule.
|
|
|
|
|
I agree with Rob. Video's aren't exactly searchable.
"I have a theory that the truth is never told during the nine-to-five hours. "
— Hunter S. Thompson
|
|
|
|
|
|
a bacon usage diagram would helpful. 
as if the facebook, twitter and message boards weren't enough - blogged
|
|
|
|
|
but I so rarely encounter "third party component"s nowadays. And when I have, the documentation has usually been incorrect, out of date, or even for a newer version than what we had. 
|
|
|
|
|
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
|
|
|
|
|
The survey is missing a key piece of information. What's "most" important - 1 or 5?
/ravi
|
|
|
|
|
I thought that as well, then I re-read the question.
"how valuable" changes everything.
Something worth $1 is not as valuable as something worth $5, so I applied the same principle.
|
|
|
|
|
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.
|
|
|
|
|
Alex Fr wrote: voting results look like handled by smoothing filter
Random noise processed by a smoothing filter!
- ns ami -
|
|
|
|
|
Absolutely, the two prior responses indicate that, one going for "1" as most valuable, the other for "5", so I guess this survey has been a waste of time for all concerned.
Except of course the messages.
|
|
|
|
|
So, idea for the next survey: in a survey, when asked to rate items as valuable, what score do you associate with "most valuable"?
(a) 1
(b) 2
(c) 3
(d) 4
(e) 5
|
|
|
|
|
What about "Other". 42 would fit the bill nicely methinks.
/ravi
|
|
|
|
|
or, as my ex-wife used to say, "it's nice to want."
Marc
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
