On Fri, Feb 27, 2009 at 6:48 PM, mdipierro <mdipie...@cs.depaul.edu> wrote:
>
> I do not like the idea of things moving out of the wiki and never
> coming back. Things will always need small updates and that it
> critical.
Small updates can happen in Wiki; when stable, they can happen in Sphinx I
think this is no problem - sphinx can always be updated; it just will not be
the same way as a wiki.
>
> We can start with that but then we need to build a web interface
> directly to the sphinx docs.
This will be some challenge, since sphinx builds indexes and cross
references on entire doc... you will be rebuilding all indexes with any
edit?
Aside from the technical challenges, this then will not be documentation in
the form of a book, which stabilizes, gets reviewed, etc.
I think if you want a wiki for everybody to easily contribute their
learnings, then a wiki is fine.
If you want dependable, readable, consistent documentation, like many, many
other projects do - Python not the least of them, then what is the basis of
what you "do not like"?
In any case, I am not for this. There are some interesting possibilities
to live sphinx, but even then, the concept of submitted vs. reviewed vs.
published changes is (in my mind) important, and differentiates this in a
fundamental and important way from a wiki.
A wiki is useful and important; it is also quite different than a document.
I am not interested in participating in degenerating a form - whose aim is
to generate a reliable, consistent, readable document - into a printed
version of a wiki, although you can do that (I just am not interested).
People like your book because you _owned_ the contents, even with the
contributions of others, and that meant a consistency which made it
readable, consistent and therefore useful.
If you want a wiki, then you don't need sphinx - google searches over wiki
pages will suffice.
I am interested in the document concept, and think a wiki is a good ground
for tilling the material which stabilizes into something worthy of being
part of a coherent form (not to diminish by any means the utility of what is
in a wiki - it just is a different form, and a different result - it is also
more accesible to contributors, and that is good).
We have had this discussion enough times. Wiki away. I will contribute to
the wiki too at times.
Let me know if you're interested in the process of creating a community
written book; in that I would be more interested.
Regards,
Yarko
>
>
> Massimo
>
> On Feb 27, 6:36 pm, Yarko Tymciurak <yark...@gmail.com> wrote:
> > On Fri, Feb 27, 2009 at 1:31 PM, Paul Eden <benchl...@gmail.com> wrote:
> > > +1 I like these ideas.
> >
> > > One thing I would add.
> >
> > > If we do have a wiki and sphinx in source control then we should have
> one
> > > place where users can search through *both* places.
> >
> > > That way they don't have to look through one and then look through the
> > > other to find answers.
> >
> > Well - by nature, this would be a diode -> that is, a one way door:
> >
> > So I can imagine how the wiki, when a page / topic gets mature and
> migrates
> > to the sphinx will point to that. But the sphinx will not point back (in
> > the case the wiki has new, not yet in sphinx updates).
> >
> > Which raises an interesting point:
> >
> > Maintenance of sphinx sources should be concerned with evlolving,
> > improving, and doing "book like" changes (cross references). New ideas
> or
> > more than slow evolutions / additions should still happen in the wiki.
> >
> > I see the wiki as being public enough and encouraging input from broader
> > population, so it _should_ go through the chaos->settling steps for a
> given
> > topic; the sphinx place should be like the cask - the place where what
> > happens is mostly mellowing (or polishing / nice diagrams, so forth).
> >
> > Having said that - Massimo called for a general organization of the Wiki
> > into gross topic areas (as I understood).
> >
> > If we agree on that, then the sphinx sources can easily reference the
> areas
> > from which they came; the wiki then should make it easy to spot any new
> > things...
> >
> > Would this satisfy your request, or did you have something more in mind?
> >
> > Yarko
> >
> >
> >
> > > Paul
> >
> > > On Fri, Feb 27, 2009 at 11:06 AM, Yarko Tymciurak <yark...@gmail.com
> >wrote:
> >
> > >> I haven't fully thought about this yet, but in general -
> > >> Wiki == freeform idea collection; I agree that some structure to
> begin
> > >> and guide is good;
> >
> > >> Good place for transient information;
> >
> > >> I would think once content is in a sphinx doc (and I agree completely
> w/
> > >> source control - much like what the Python 3 Patterns book is
> following) it
> > >> should be pulled form the wiki (maybe a final revision referring to
> the
> > >> "published" page, and then new updates maintained in sphinx doc).
> >
> > >> This will prevent the considerable problem of diverging documentation
> ("I
> > >> documented it here; Oh! Look - there's something similar, but a little
> > >> different here - which is right? which is current?")
> >
> > >> Perhaps a feedback look from sphinx would be useful (we organized best
> w/
> > >> these sections, so we now re-organize the wiki to - at least at a high
> level
> > >> - match).
> >
> > >> Anyway, I have an idea, I don't know where to put it, I want to share
> it
> > >> --- this is definitely wiki space, and others can add / update....
> >
> > >> Just rambling thoughts during lunch...
> >
> > >> Yarko
> >
> > >> On Fri, Feb 27, 2009 at 9:27 AM, cjparsons <cjparso...@yahoo.co.uk
> >wrote:
> >
> > >>> > Use the wiki for the initial gathering of doc pages, then after the
> > >>> > first sphinx-based documentation is produced, just clean the wiki
> of
> > >>> > those pages. After that, just use the wiki for contributed recipes
> > >>> > and other pages, some of which are selectively migrated to sphinx.
> > >>> > Keep the changes due to new releases in sphinx only.
> >
> > >>> > Just asking.
> > >>> +1. Once the accepted documentation is there I think we need to keep
> > >>> the wiki to recipies so as not to confuse new users as to where to
> > >>> look for the greatest information. I know I found having the draft
> > >>> manual, alter ego, cookbook, source code etc. to look at for answers
> > >>> quite confusing (though more is better than less, obviously).
> >
> > > --
> > > Best Regards,
> >
> > > Paul Eden
> >
> > > "...and a little looking out for the other guy too."
> > > - Mr. Smith
> >
>
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"web2py Web Framework" group.
To post to this group, send email to web2py@googlegroups.com
To unsubscribe from this group, send email to
web2py+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/web2py?hl=en
-~----------~----~----~----~------~----~------~--~---
