On Jan 21, 2013, at 17:06, Andy Fingerhut wrote: > Yes, we do have the technology, and have for years now. The technology > isn't the hard part in this case. The only barrier to entry is the > willingness and ability to spend time, more time, and yet more time ...
I've been interested in mechanized documentation for decades. I have speculated about system designs and even generated working code in the area at times. I really like Codeq's approach, for several reasons: * The notion of "code quanta" is new (to me, at least) and seems useful. * The use (and extension) of Git as the system's basis allows Codeq to take advantage of good (and strongly adopted) technology. * The use of a flexible, powerful, and scalable database (Datomic) as the data store allows arbitrary inputs and outputs. (I'm _really_ down on the "information silo" nature of most current doc systems.) That said, use of Codeq should be be either invisible or optional. If I type (doc foo) into my REPL, I should have to worry about infrastructure. Although I wouldn't expect a tsunami of volunteer documenters, I think we might see a fair amount of activity, given the pent-up demand that we've seen expressed on this list. Whether the activity persists will depend on how convenient and useful the resulting system seems. Given Codeq's structure and Git-friendliness, it might be useful to set up a doc repo to document each "base" code repo. I'd map each file in the base repo to a directory in Git and each code quantum in the base repo to a structured (eg, YAML) documentation file. This would give the documenter(s) plenty of "elbow room" for adding text, metadata, etc. > I wouldn't say it would defuse any arguments about what information > should or shouldn't be included. Any such arguments would move from > the Clojure team to whoever maintains the enhanced docstrings. :-) > One could imagine allowing multiple sets of such enhanced-docstrings > to be distributed from multiple parties, and Clojure users could pick > and choose which ones they prefer to look at. However, there is > definitely an advantage to having one common source for such things. One advantage of storing the documentation separately from the code is that a given piece of code can have any number of documentation files. For example, in the system I sketched above, divisive arguments about "what belongs in the documentation" could turn (harmlessly) into Git forks and branches. If I get inspired, maybe I'll create a sample repo for folks to look over. If the basics seem solid, a trial repo could be mechanically populated from (say) assorted Clojure libraries. -r -- http://www.cfcl.com/rdm Rich Morin http://www.cfcl.com/rdm/resume r...@cfcl.com http://www.cfcl.com/rdm/weblog +1 650-873-7841 Software system design, development, and documentation -- 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
