IMO it can often be a lack of readable, searchable, nice-to-navigate text/hypertext that can be a barrier to entry. In fact all of these are unfortunately common in various parts of the geekosphere:
1. Projects whose *only* documentation (or the only version of certain key information) is in videos. Not searchable. Not easy to navigate to a particular part (need to remember roughly when it is, or rewatch half the thing). Expensive for mobile users with capped or per-megabyte data plans. 2. Projects whose *only* documentation is reference-type material that does not introduce the library/whatever to total n00bs. A common case is for there to be beautifully detailed Javadoc for every public class, method, and constant in some Java library, but nothing to give a n00b a clue as to where to start using it. Sometimes it's fairly obvious (there's a problem domain class Foo that it makes sense to instantiate first, and that class has a public constructor, has a public static getInstance method, or sits next to a FooFactory class in the same package, and this is well-documented) but often it's not. Regardless, it would be preferable for there to be a "getting started" guide. With a textual version that can be searched with grep or other tools. 3. Projects whose *only* documentation is a getting-started guide, tour, tutorial, or similar. When one knows the basic patterns of usage but wants to recall the argument order for the (burbling-mumblefrotz ...) function, having to find where it was introduced in a tutorial (which chapter? The one on mumbling or the one on burbling? Near the start, middle, or end? Page 2 or 29???) is a pain in the neck. A reference is organized differently, for making a specific known entity easy to re-find. Javadocs and Clojure docstrings are good for this. In particular: * Every key fact, example, or other piece of documentation should exist somewhere in a form that Google can find on the web and grep can find in your local copy if you make one. And that local copy shouldn't cost a fortune to download and a ton-lot of disk space to keep, nor should it be a pain in the ass to scroll forward and backward through. Ideally, it should be browseable on a fairly low-spec machine if need be, as well, even one that makes video playback stutter at 3 FPS. * There needs to be two differently organized written forms of documentation: one oriented around discovering how to do X, for people that don't know the name of the function, class, method, or other entity that does X; and one oriented around specifying precisely the usage, behavior, and applicable preconditions/gotchas/etc. of a particular function, method, class, or whatever that one *does* know the name to. The latter is typically partly machine-generated and organized hierarchically and alphabetically by package/namespace and name. The former tends to be mainly human-authored and often linear, or at most a few branches, of exposition, which shows how the parts are interrelated and how to build up from those parts to useful working systems of some sort. Videos do have their uses, but should not be regarded as *substitutes* for either written reference documentation or written tutorial documentation, and the latter are not substitutes for one another. I'd regard a lack of good *written* introductory material as a much worse barrier to entry than a lack of good videos, where the subject matter lends itself to textual exposition (math, programming). (That last restriction of scope is necessary; no amount of written material telling people how to play golf, for instance, is likely to beat a good video showing a proper stance and backswing. Gross motor skills in general benefit strongly from, at minimum, video clips of key moves/actions. Most things benefit from the occasional illustrative still image, however.) On Sun, Nov 10, 2013 at 10:10 AM, Ryan Waters <ryan.or...@gmail.com> wrote: > Thank you Saravana. I'm finding a number of the posts David Nolen [1] > has written on his blog to be invaluable. Once I figure out what mix of > libraries I'll be using I can let you know! > > [1] http://swannodette.github.io/ > > > On Sat, Nov 9, 2013 at 12:33 PM, Ryan Neufeld <r...@cognitect.com> wrote: > >> Stuart Halloway is doing a presentation and we’ll be dumping a lot more >> new stuff into the repository. I made a mistake in saying we had an >> announcement, it’s more just that we’ll be talking more publicly about what >> we’re working on following next week. >> >> -Ryan >> >> >> On November 8, 2013 at 5:39:34 PM, Andreas Liljeqvist >> (bon...@gmail.com<//bon...@gmail.com>) >> wrote: >> >> Will there by any presentation on Pedestal, or just announcements? >> >> >> On Fri, Nov 8, 2013 at 1:38 AM, Ryan Neufeld <r...@thinkrelevance.com>wrote: >> >>> Speaking as a core Pedestal team member and engineer at Cognitect I can >>> say we are *very* serious about continuing to grow and support >>> Pedestal. It may be quiet, but we're using the entirety of Pedestal with a >>> number of client and are fervently preparing a number of new features and >>> improvements we plan to announce at the Conj next week. Further, we've even >>> begun selling commercial support that includes Pedestal[1]. >>> >>> ClojureScript One was a huge influence on pedestal-app, but you're >>> completely right that we've abandoned it and should probably wind things >>> down there. >>> >>> Are there any other questions I can field while I'm here? >>> >>> -Ryan >>> >>> [1]: http://cognitect.com/Cognitect-Support-Services.pdf >>> >>> >>> On Thursday, November 7, 2013 5:30:59 PM UTC-5, Marko Kocić wrote: >>>> >>>> Hi all, >>>> >>>> I'd like to hear opinions about Pedestal from the people that have been >>>> playing more with it. Right now I started looking at it, and like some of >>>> the things, but not sure should I invest more time learning it. While I do >>>> like some concepts, I'm not sure is it going to became abandonware like >>>> Clojurescript One (does anyone reemembers it anymore). >>>> >>>> So far, after initial splash, I haven't seen large community interest >>>> in it. The number of aproachable getting started guides and hands on >>>> tutorials is missing. That might change over time, but I'm afraid that next >>>> year this time we'll get another Clojurescript one page application >>>> framework not much related with Pedestal. How serious Cognitect/Relevance >>>> is about it? >>>> >>>> Best regards, >>>> Marko >>>> >>>> -- >>> -- >>> You received this message because you are subscribed to the Google >>> Groups "Clojure" group. >>> To post to this group, send email to clojure@googlegroups.com >>> Note that posts from new members are moderated - please be patient with >>> your first post. >>> To unsubscribe from this group, send email to >>> clojure+unsubscr...@googlegroups.com >>> For more options, visit this group at >>> http://groups.google.com/group/clojure?hl=en >>> --- >>> You received this message because you are subscribed to the Google >>> Groups "Clojure" group. >>> To unsubscribe from this group and stop receiving emails from it, send >>> an email to clojure+unsubscr...@googlegroups.com. >>> For more options, visit https://groups.google.com/groups/opt_out. >>> >> >> -- >> -- >> You received this message because you are subscribed to the Google >> Groups "Clojure" group. >> To post to this group, send email to clojure@googlegroups.com >> Note that posts from new members are moderated - please be patient with >> your first post. >> To unsubscribe from this group, send email to >> clojure+unsubscr...@googlegroups.com >> For more options, visit this group at >> http://groups.google.com/group/clojure?hl=en >> --- >> You received this message because you are subscribed to a topic in the >> Google Groups "Clojure" group. >> To unsubscribe from this topic, visit >> https://groups.google.com/d/topic/clojure/XQ4wuUc0bCk/unsubscribe. >> To unsubscribe from this group and all its topics, send an email to >> clojure+unsubscr...@googlegroups.com. >> >> For more options, visit https://groups.google.com/groups/opt_out. >> >> -- >> -- >> You received this message because you are subscribed to the Google >> Groups "Clojure" group. >> To post to this group, send email to clojure@googlegroups.com >> Note that posts from new members are moderated - please be patient with >> your first post. >> To unsubscribe from this group, send email to >> clojure+unsubscr...@googlegroups.com >> For more options, visit this group at >> http://groups.google.com/group/clojure?hl=en >> --- >> You received this message because you are subscribed to the Google Groups >> "Clojure" group. >> To unsubscribe from this group and stop receiving emails from it, send an >> email to clojure+unsubscr...@googlegroups.com. >> For more options, visit https://groups.google.com/groups/opt_out. >> > > -- > -- > You received this message because you are subscribed to the Google > Groups "Clojure" group. > To post to this group, send email to clojure@googlegroups.com > Note that posts from new members are moderated - please be patient with > your first post. > To unsubscribe from this group, send email to > clojure+unsubscr...@googlegroups.com > For more options, visit this group at > http://groups.google.com/group/clojure?hl=en > --- > You received this message because you are subscribed to the Google Groups > "Clojure" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to clojure+unsubscr...@googlegroups.com. > For more options, visit https://groups.google.com/groups/opt_out. > -- -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.
