Very exaustive comment, that reminded me of a beautiful series of articles by Jacob Kaplan-Moss on "Writing great documentation<http://jacobian.org/writing/great-documentation/>". There is a presentation<http://pyvideo.org/video/403/pycon-2011--writing-great-documentation>, too.
Il giorno lunedì 11 novembre 2013 07:04:09 UTC+1, Cedric Greevey ha scritto: > > 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....@gmail.com<javascript:> > > 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 >> <ry...@cognitect.com<javascript:> >> > 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<javascript:>) >>> wrote: >>> >>> Will there by any presentation on Pedestal, or just announcements? >>> >>> >>> On Fri, Nov 8, 2013 at 1:38 AM, Ryan Neufeld >>> <ry...@thinkrelevance.com<javascript:> >>> > 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 clo...@googlegroups.com<javascript:> >>>> Note that posts from new members are moderated - please be patient with >>>> your first post. >>>> To unsubscribe from this group, send email to >>>> clojure+u...@googlegroups.com <javascript:> >>>> 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+u...@googlegroups.com <javascript:>. >>>> 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 clo...@googlegroups.com<javascript:> >>> Note that posts from new members are moderated - please be patient with >>> your first post. >>> To unsubscribe from this group, send email to >>> clojure+u...@googlegroups.com <javascript:> >>> 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+u...@googlegroups.com <javascript:>. >>> >>> 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 clo...@googlegroups.com<javascript:> >>> Note that posts from new members are moderated - please be patient with >>> your first post. >>> To unsubscribe from this group, send email to >>> clojure+u...@googlegroups.com <javascript:> >>> 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+u...@googlegroups.com <javascript:>. >>> 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 clo...@googlegroups.com<javascript:> >> Note that posts from new members are moderated - please be patient with >> your first post. >> To unsubscribe from this group, send email to >> clojure+u...@googlegroups.com <javascript:> >> 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+u...@googlegroups.com <javascript:>. >> 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.
