On Thu, Oct 1, 2009 at 11:27 PM, Peter Alexander <[email protected]> wrote: > 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 :) >
I gonna expand on my thoughts here. I think that there should possibly be something like this posted on the documentation section of the static Cython portal page: "Introduction To Cython", "Tutorials", "Reference Guide", "User Guide", "Videos and WebCasts", "White Papers", etc... "Introduction To Cython" would be the overview and introduction including all sorts of introductory topics and links. "Tutorials" would be a self contained sphinx doc with a TOC that includes tutorials of general, topic and domain specific "dive-in and get your hair wet" material. Here we "hold the reader's hand" and walk them through usage. "Reference Guide" would be an elaborate "outline" of facts. Used for fast access to succinct information. "User Guide" would essentially be the reference guide outline but in paragraph form which includes more detailed info, caveats, gotchas. This would help keep the ref guide succinct in that "detail" can be linked to from that document to this document (as well as tutorial sections, etc..) "Videos and Webcasts" would be.. well this is self-explanatory... "White Papers" would be any pdf like documents available.. etc. ..Now, All examples/snippets should be global, in its own directory, so each documentation can "embed" the example it needs. Hell.. if we were sophisticated one day.. video snippets might also be "embedded" or at least linked to. Lastly, of my thoughts for now is, the subject of "search portals". Common, current search technology is one of my pet-peeves in that a search lead you to a page and not to the item context within the page itself. To mitigate this hindrance, I think each topic should reside each within in its own page. Also, to accommodate my vision of inter-documentary documentation a global search engine will be needed. Xapian, could be considered.. it is exceptional with python bindings. Or google or what ever.. I defer. What's your opinion... enquiring minds want to know. :-) _______________________________________________ Cython-dev mailing list [email protected] http://codespeak.net/mailman/listinfo/cython-dev
