"new book" in the docs should be moved to a wiki.
alind
will allow everybody to contribute to the documentation as and when he/
she finds the time/urge to do so. Login can be made compulsory to the
the particular wiki for blame-gaming.
This will help in speeding up the docs/new-book towards mature-ness
and completeness. (As I can see that he new-book is not progressing
fast enough). Wiki based system can help a lot by using crowd-
sourcing.
Alessandro Molina
the issues related to wrong informations/spam.
Found a good way to manage this complexity a wiki system might indeed
help doc development making it easier to contribute for everyone that
has a few spare minutes to invest and quick to fix minor errors.
Maybe we can consider a two way process where there is a wiki that
than gets reviewed and frozen as static doc for every release and
people can choose both to look at the wiki for recent but not verified
informations or to the frozen doc for verified but older informations.
> --
> You received this message because you are subscribed to the Google Groups "TurboGears" group.
> To post to this group, send email to turbo...@googlegroups.com.
> To unsubscribe from this group, send email to turbogears+...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/turbogears?hl=en.
>
Christoph Zwerschke
> I think this is a very good idea, we just have to find a way to manage
> the issues related to wrong informations/spam.
That's the big problem. Our experience with using a wiki for the TG1
docs was not very good. Granted, we succeeded in creating fairly
extensive online docs, but they were a mixed bag of good articles,
not-so-good articles, bad articles, half done and outdated articles; and
nobody had enough time & expertise to review these, so they became more
and more rotten and unwieldy. We were heavily haunted by spammers, but
nobody took the time to regularly check the site, delete the spam users
and their entries. In the end, I did all the clean-up and converted the
whole wiki to Sphinx docs. Though I did some reviewing and editing, they
are still a mixed bag, incomplete and inconsistent.
People always hope that a huge crowd is there to write the articles, but
in reality the mass are only consumers, not producers. And then they hop
someday someone will review and edit all the stuff, but in reality this
will never happen, because it is more time-consuming and boring to
review and rewrite half-baked and disarranged stuff written by other
people than writing consistent docs from scratch all by yourself.
So a wiki system for TG2 may help, but it still needs maintainers and
editors who review and remove spam and organize all the articles into a
reasonable and consistent whole. Don't underestimate these efforts.
The other problem is how to cover the different versions with one wiki.
In the TG1 wiki we used different prefixes 1.0, 1.1 and 1.5 for the
different versions, but this made the docs even more unwieldy, and while
the 1.0 docs were still quite extensive, the 1.1 and 1.5 were much more
sparse, because again nobody had enough time & expertise & motivation to
copy updated versions of all the old 1.0 docs to the 1.1 and 1.5 sections.
Also, as far as I understand, Michael's idea was to write a new "book".
While a wiki may be useful in collecting tutorials and recipes, I doubt
that it can help in creating a more book-like documentation.
-- Christoph
Carlos Daniel Ruvalcaba Valenzuela
wiki is very prone to spam, a good idea would be to give accounts to
the wiki only to members of the list who request them so at least that
would help stop spam, new contributors would only need to subscribe
and request access (which should be given relatively freely to anyone
who requests it).
Having a wiki would be like having a playground to shape up and
experiment docs or tutorials in a more approachable way than checking
out the docs from the repository, the later implies that you should
have some sort of authority on the topic at hand as they are the
official docs that go to the page.
Plus a wiki is easier to edit, current docs require you to checkout
source, modify, commit back, merge, wait for next update cycle, with
wiki you log, modify/add and it goes live.
Regards,
Carlos Daniel Ruvalcaba Valenzuela
Alessandro Molina
> We were heavily haunted by spammers, but nobody took the time to regularly
> check the site, delete the spam users and their entries. In the end, I did
> all the clean-up and converted the whole wiki to Sphinx docs.
>
My idea is somewhat to have a wiki system that is RST based and can
generate sphinx doc automatically.
This way before each and every release one of the main steps would be
to review the doc and check is valid and then freeze it building it
with sphinx to a static page.
This way we would have something like:
/docs/dev -> wiki based
/docs/current -> static html (rst based wiki frozen)
> The other problem is how to cover the different versions with one wiki. In
> the TG1 wiki we used different prefixes 1.0, 1.1 and 1.5 for the different
> versions.
Well, this is probably more related to the fact that 1.0, 1.1 and 1.5
continued to live in parallel due to major incompatibilities.
TG2 is having a more straightforward development process and I hope we
won't have that issue again.
Michael Pedersen
Alessandro Molina
> I can't help but be amused that a week ago I posted a rant about wikis
> (see http://codersbuffet.blogspot.com/2012/01/wikis-suck.html ), and then
> this topic comes up.
>
I mostly agree with your points, but actually, apart being
authoritative, they apply also to sphinx.
I'm really curious about this because even with a closed system it
should be an improvement to the doc management process.
it should mean switching from:
- git pull doc
- apply your changes
- build doc
- wait around half a minute
- open built doc in the browser to check your changes.
to:
- click edit
- apply your changes
- check your changes
> My views? Use the git docs. They work. They got hampered by my real life
> requirements over the past 6 months. I
>
Well nothing prevents your from still keeping git as the wiki storage system.
To me a wiki is just an interaction pattern, not its implementation.
Adding inplace online edit to readthedocs.org for example would
perfectly fit my definition of wiki system and might only speed up doc
development process.
werner
> I can't help but be amused that a week ago I posted a rant about wikis
> (see http://codersbuffet.blogspot.com/2012/01/wikis-suck.html ), and
> then this topic comes up.
>
> My views? Use the git docs. They work. They got hampered by my real
> life requirements over the past 6 months. I'm finally settling back
> into working again, and am focusing more on Hiring Pond (the main
> application to be developed throughout the book), and then the book
> itself. Having the code done/tested will help me produce a higher
> quality end result on the book.
>
> Don't use wiki. I know they're popular. I know people like them. I
> just don't agree with them, and wish I could figure out the solution.
> If i ever *do* figure out a documentation tool that addresses my
> issues, I'll work on it. Still trying, though.
might be a solution.
http://tosh.pl/gminick/gsoc/sphinx/
Werner
Alessandro Molina
integrated into the main sphinx codebase and it seems that the source
code tree has changed a lot since then.
I saw https://github.com/pv/pydocweb which seems really similar to
that idea and has been created to write NumPy documentation.