On Feb 9, 2010, at 1:58 AM, Beerc wrote: > Some experiences from many years of working with wikis, small to > medium to large:
This all sounds very sensible. We ought to take advantage of homogeneous material where we can find it. Docstrings in particular could feed a set of wiki pages (read-only, unless someone wants to take on the back-edit problem). On the choice of wiki, I'd take a look at MoinMoin (with the caveat that I have all of about 20 minutes experience looking at it). It seems relatively mature, uses plain-text files, uses a MediaWiki-flavor markup, and is written in Python to boot. (I agree that this isn't a major point, but it's at least a plus, in that it's the home team, and as a group we have the resources to contribute there if we really need a feature or a fix. And if it's really good, I'd consider it as an adjunct to a web2py website of my own.) > > ---------- Autoconversion: > It is very hard to *automatically* convert any bigger, heterogenous > material to a *good* wiki format. Attemptions are plenty, all of them > failed. Probably it is impossible. Except conversions from other wikis > (e.g. from MediaWiki to DokuWiki or vice versa). Causes are many. Lots > of. > > (Opposite ends: manual conversion, small material, homogenous > material, poor quality wiki.) > > It is very hard to *automatically* convert any wiki to a *good* book > format. Probably impossible. > > (Opposite ends: manual conversion, poor quality book.) > > I suggest abdicating the hope for autoconversions. Superfluous work. > > ---------- Why HTML? > Main argument for an *HTML documentation*: anybody can link into one > of its pages. This seemingly simple feature brings huge benefits over > the time. > > Internal and external linking and link handling capabilities in PDF > and other formats are very limited. Hypertext offers huge inherent > benefits, but document formats (PDF, CHM, DOC, RTF etc.) are > essentially sequential. > > Sequential structure of conventional documents helps *learning* and > storytelling. Structure of heavily linked hypertexts helps *writing* > (for example thru ad-hoc linking of new subpages) and similarity based > searching (thru "surfing"). It follows that conventional documents > helps beginners, hypertexts helps to write and read complete > documentations. > > ---------- Why wiki? > Main arguments for a *wiki* (online, editable HTML documentation): > * Simple syntax, so anybody can contribute. (Better, if only > registered users can.) > * Unlimited page revisions. So you can compare them. Easy to find the > modifications with colored, side by side diff (built in feature in > better wikis). > * List of recent changes. So easy to find the new parts. > * Section editing helps quick changes. > * Easy to embed images in many formats and arbitrary sizes. > * Page locking or conflict resolution precludes edit conflicts. > > ---------- Which wiki? > Web2py has a wiki, with unique, powerful features: T3 (e.g. > wiki.web2py.com). While I'm delighted with T3, and I hope its wiki > capabilities will improve over the time, *now* and in the near future > it isn't appropriate for carrying a *complete* documentation of a > serious software project. > > There are lots of wiki. There are only a few good ones. While it can > be hotly debated, I'm sure DokuWiki is the best choice for documenting > web2py. Because: > * All data is stored in plain text files. So we can versioning them, > parallelly with other parts of the project. And it is easy to generate > wiki pages. > * DokuWiki is easy to use, feature rich and standards-compliant. > * If a project using Trac, then probably it is better choice than > DokuWiki. (Trac uses plain text files, easy to use, moderately feature > rich.) But web2py project don't using Trac. > * If a project similar to Wikipedia, then probably it is better choice > than DokuWiki. But web2py: > ** less popular than Wikipedia (yet ;), so don't require eminent > scalability of internal search, > ** and don't require advanced media handling (media revisions etc.). > > (Scalability of search function in non-public, large dokuwikis is > problematic. In public dokuwikis web search engines can substitute > internal search.) > > Yes, DokuWiki is PHP-based. So we will lose the purity. Bearable pain. > > ---------- How to wiki? > This deserves longer explanation. -- You received this message because you are subscribed to the Google Groups "web2py-users" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
