When we started writing the Wikidot documentation, we did not have live templates, ListPages, nor did we have a thriving community. The documentation section is starting to show its age, and we want to take that chance to redo it, properly.

What does "redo" mean? I'll start by relisting the main problems that I see with the doc and the way it's made:

The Wikidot syntax page is far too long, both because it covers too much, and because it is too verbose in many areas.

The doc does not use modern techniques for organization (ListPages, tags) and presentation (live templates, content sections).

The doc is not user-fixable, so even trivial errors are painful to report and fix.

The doc allows per-page comments, but these short-term discussions fit uncomfortably with the long term documentation.

So, I've started a new site at http://doc.wikidot.com. You'll see some ideas on the front page; for the rest the site is just the default template, with no structure.

I've seen it. Nice. Please wait before copying too much content from the existing site, as I'd like to also think about how to redesign the actual pages. For example, this page shows an alternative way of documenting a module that may work better.

We can get rid of the lifecycle tags: all module documentation will always be stable

We can simplify the admin page accordingly. Simpler is always better

We should start a discussion page (one page we edit) on the site, for this thread

As Shane suggested, it's nice to create a _start page for each section that does the summarization

These pages (there will be several) can then be included into the main page

I'd really avoid using other includes for now, they make it much harder to edit and understand the site

I'll come back with a more detailed proposal for the module doc page itself, but IMO it should be something like:

short summary of what the module does

code examples of typical cases (these can be copied/pasted)

a code template with all arguments that can be copied/pasted and then edited

known limitations

a reference section that explains all functionality

optionally a link to a whiteboard design sketch for new functionality

a link to the forum for questions

an edited FAQ of questions/answers

We also need IMO to normalize the specification of selectors and variables, so that these are documented one time only (pages in the doc: section). Then in the module we only need to explain, "Selectors: category, tags, parent, …"