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.
Please don't yet copy content from the existing site: we need to think about how to redesign the individual pages to be more readable.
Main sections for the documentation:
Discussion is on the projects Forum.
For the first version of this site we will make:
- A new changelog, that uses pages/comments instead of the old forum.
- New documentation for the most important modules
- A new version of the Wikidot syntax page
Module documentation
Some ideas about how the documentation should work:
- One module per page, clearly, in a module: category DONE
- Modules can be organized using tags:
- functional: "management", "layout", "searching", "members", etc. DONE
- lifecycle: "_concept", "_experimental", "_stable", "_deprecated", etc. DONE
- Using templating to organize the page
- Using ListPages to show lists of modules DONE
- Discussion of modules in a separate wiki forum, not on the module pages
In each module page:
- What the module does, and why
- Common examples of use
- Detailed syntax and specifications
- Frequently asked questions for this module
Change log
Some ideas about how the change log should work:
- Standard micro-blogging model, like Chatter package
- People can watch the changelog section
Wikidot syntax
The current page is huge, and complex to read. We experimented already with a quick reference navigator, and that seems to work. So, some ideas about how the syntax should be written:
- One cover page that is a quick reference, with links to further pages.
- One page per syntax area, in the syntax: section.
- 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).
- Discussion of the syntax in a separate forum.
For each syntax page:
- What the syntax does, and why
- Common examples of use
- Detailed specifications
- Frequently asked questions for this syntax
What this site is not
- The Handbook, which is a 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
Why move discussion to a forum?
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.
