I agree with Massimo. Wiki concept is proven and everyone understands
howto update (and navigate) wiki content. Small updates "made easy" is
critical.
Keep it simple, keep the docs in a central wiki that is put up onto
appengine (so we all have fast access), and that wiki software itself
will improve web2py overtime. Like wikipedia/mediawiki.
Efe
On Feb 28, 8:48 am, 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.
>
> We can start with that but then we need to build a web interface
> directly to the sphinx docs.
>
> 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
-~----------~----~----~----~------~----~------~--~---
