On Nov 1, 2011, at 11:40 AM, Brian Gernhardt wrote: >My quick $0.02: > >>On Nov 1, 2011, at 8:55 AM, Alvis Yardley wrote: >> >> (1) The new Parrot documentation set will, of course, reside on Github, >> whether in a branch or on a separate repo, I do not know. >> >> Note: I need direction on this. It seems to me a branch to the master >> should suffice, but I do not, as yet, sufficiently understand Github to >> assess whether or not this is the correct approach. >> > I would say that it's better to keep the documentation close to the > code. Then at least there's less of a barrier for coders to > work/check the documentation and people working on documentation have > ready access to the source. If the documentation becomes overly large > or we start doing things like collecting translations, we can split it > off later.
On further reflection, I must confess: I do not understand what you mean by "keep[ing] the documentation close to the code." Perhaps, I was too vague in my earlier statements. I'll try to be a'bit more specific. Presently, there are, to my admittedly poorly-informed way of thinking, four, broad categories of documentation: (1) Everything in '/docs' or on docs.parrot.org; (2) The various README-type documents throughout the various directories; (3) Source code documentation; and (4) Everything out-dated and out on the net. To this, we plan to add two more categories (or, perhaps, replace most of (1) above with (5) below), (5) The "Developer," "User," and "Reference" manuals and (6) Pod and pod2man pages of the binaries. So, what am I missing or misunderstanding? Or were you just addressing my "separate repo" statement above? Or, were you refering to something else entirely of which I am unaware/misunderstanding ...? Thanks again for all of your help/input. Alvis _______________________________________________ http://lists.parrot.org/mailman/listinfo/parrot-dev
