Some experiences from many years of working with wikis, small to medium to large:
---------- 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.
