On Thu, Oct 1, 2009 at 10:13 PM, Peter Alexander <[email protected]> wrote: > On Thu, Oct 1, 2009 at 9:39 PM, Robert Bradshaw > <[email protected]> wrote: >> On Oct 1, 2009, at 12:21 AM, Peter Alexander wrote: >> >>> Hi Robert. I have a branch repo at >>> http://bitbucket.org/travlr/cython-docs . That should suffice for now, >>> I'd think. Unless you all want it differently. >> >> Yes, that's totally fine. Distributed revision control is nice :) >> >>> At this point I've redone the super-structure and am iterating inward. >>> Conciseness is my goal. Let me know, at any time, your thoughts or >>> vision do not coincide with what I do.. >> >> Looks good. I think most of the language basics could be put later, >> with the exception of typing. So the first three sections could be >> overview, data typing, and compilation. After those three, we could >> move on to the topic-specific tutorials. >> >> - Robert >> >> _______________________________________________ >> Cython-dev mailing list >> [email protected] >> http://codespeak.net/mailman/listinfo/cython-dev >> > > I look at what I'm working on now as a "reference guide" should be > solely considered as a "get your fingers on the answer, quickly", > guide. > > Basically, what I'm thinking of for this, is a very complete outline > stating the language rules, particulars, etc., with cross-references > galore, indexing, and lots of examples, etc., > > I believe that a multiplicity of documentation sources is a good > thing.. Tutorial, reference, and "papers".. etc, etc. > > Tutorials as introductory "dive-in, and get you hair wet" type, and > acomplete, very well thought out, no-nonsense reference material for > those engaged in their project that "just want the answer that second" > (like me) kind a guy/gal. > > So.. personally I am invested in the reference type, but I totally > think that domain specific tutorials would be great for Cython to > support. And a necessity, you might say. > > But, for now I'd like to concentrate on making the ref guide succinct, > accessible, and most of all... complete. > > I also very much appreciate input from others. So please speak up when > you want to... so we can get this right. > > ~Peter >
Now, that I'm thinking about it.. the "overview" could itself be a seperate document. Kind of a like "Getting Started..." or "Welcome..." documentation. I also think that cross-documentation linking is essential, so as to not duplicate information all over the place. So for instance in the "ref" guide, link to the overview... link to general and domain specific material in the tutorials. Link, link, link.. index.. etc.. blah blah blah In other words.. The thought process of "structure" should be inter-documentary. Ok, lets hear comments, ideas, etc... please :) _______________________________________________ Cython-dev mailing list [email protected] http://codespeak.net/mailman/listinfo/cython-dev
