This site will act as a new home for the official Wikidot documentation. "Official" means that when the Wikidot team makes changes to the wikidot.com software, this is the place we will document that. However, in the spirit of Wikidot we allow any registered Wikidot user to edit and improve the documentation. A big problem with the old doc pages was that when you spotted an error, you could not fix it.
Main sections for the documentation:
Discussion is on the projects Forum.
On this site, we have:
- A new section dedicated to documentation articles
- Divided and reorganised the syntax
- Arranged the modules into a single category
- Placed short summaries of the modules into the short category
The current page is huge, and complex to read. The new system has one page per syntax, and all of those pages are included into the full Syntax guide.
- One cover page that is a quick reference, with links to further pages.
- One page per syntax section, in the “syntax” category
- One "complete" page that links in every page in the syntax section into a single huge page (for those who want a dump of the full syntax).
In each module page:
- What the module does, and why
- Common examples of use
- Detailed syntax and specifications
- Frequently asked questions for this module
Some ideas about how the change log should work:
- Standard micro-blogging model, like Chatter package
- People can watch the changelog section
What this site is not
- The Handbook, which is a multi-lingual guide built by users for users
- The Snippets site, which is a repository of reusable code
- The Community site, which is a place for new and old users to discuss
No More Discussion
In the current doc we allow per-page discussions. It started so people could report errata and make suggestions for improvements. It has become, inevitably, a kind of help desk, as people ask "how do I do such and such?"
This mixes long-term content (the documentation itself) with short term content (questions and their answers). It may be interesting to collect "frequently asked questions" but the raw discussion thread is not valuable.
It's simpler to let competent people edit the page directly, and divert all other discussion into temporary forum threads that can be closed… such as on the community site.