On Wed, Apr 30, 2014 at 4:18 AM, Phil Hagelberg <p...@hagelb.org> wrote:
> On Tuesday, April 29, 2014 9:08:48 PM UTC-7, Mars0i wrote: >> >> Oh, sorry--you also asked what I meant by "detracts from" what's >> important. If a documentation formatting/organizing/coding system required >> learning a lot, figuring out a lot, adding information that is unlikely to >> be helpful >> > > Imagine you're reading through some documentation and you notice a > problem. Maybe a typo, or something out of date, or something that's > confusing that you could explain better. In one scenario there's a "git > clone" link in the sidebar to a repository that contains a bunch of > markdown files. In another scenario there's an HTML rendering generated > from a literate programming project where the prose is intermixed with the > code and requires a specific version of org-mode and the knowledge of how > to "untangle" something in order to render it. > > Guess which one is going to get improved. > The answer is not immediately obvious to me. Since I don't use emacs, I would probably have found the former easier. Having said that, perhaps everybody else who are capable of contributing are already comfortable with the literal programming tool. Or perhaps I would find out it doesn't take too much effort to contribute once I learn the basics. And perhaps this kind of documentation is works much better for this specific project, seeing the code and the docs side by side. I'm going to risk saying, perhaps there is an inversely proportional relationship between markdown proficiency/preference and contributed value in a technical community. I'm not saying documentation as a bunch of markdown files sucks. I'm just not sure if it would shown to be objectively superior to the less accessible literate programming, in the context of the quality of contributions and perhaps the health of the project. > > -Phil > > -- > 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/d/optout. > -- Kind Regards, Atamert Ölçgen -+- --+ +++ www.muhuk.com -- 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/d/optout.
