Improve documentation

[ddeboer]

Let’s work together to improve the Zotonic documentation! Good documentation is important because it:

• helps beginners get on the Zotonic track
• promotes best practices amongst seasoned developers
• draws in prospective Zotonic developers that are currently comparing web frameworks and base their evaluation (partly) on the quality of the docs available.

In other words, good documentation helps in building a larger community of Zotonic developers and contributors. Let’s focus on making the docs complete and developer-friendly.

So:

1. If you’re looking up anything (whatever it is) in the docs, and they are incomplete, inaccurate or simply nonexistent on the subject, let us know here so we can make the docs complete.
2. If you’re reading the docs and stumble upon things that are unclear, ungrammatical or hard to understand, let us know here so we can improve clarity and readability.
3. Please dump any random thoughts for improving the docs here.
4. Of course, if you have some time, please open a PR to fix the issue right away. :wink.

See also the specific issues labelled documentation.

[ddeboer]

• Thematic cookbook categories: the division frontend/admin/shell/‘just enough’ doesn’t make that much sense.

[ddeboer]

• [x] Document all notifications.

[mmzeeman]

• Document zotonic's shell scripts like debug, etop, startsite

The are important to get started.

Oops, they are documented... I couldn't find them by searching for `add siteanddebug``, also not by glancing over the index. http://zotonic.com/docs/0.13/manuals/cli.html

[ddeboer]

Make cookbooks more to the point by dropping the fixed TOC structure, including ‘Assumptions’ and other unnecessary parts: cf. http://zotonic.com/docs/latest/cookbook/frontend-module-override.html.

[mworrell]

Re: cookbooks, indeed it might be better to come quickly to the gist of the cookbook entry. That will make it easier to read and get up & running.

[ddeboer]

• [x] document observe_acl_is_allowed.

[ddeboer]

• [x] http://zotonic.com/docs/latest/ref/models/model_rsc.html doesn’t list rsc.modified

[ddeboer]

• [ ] document depcache

[ddeboer]

• [ ] document request/response cycle (web server, dispatch, controller)

[row-b]

• [ ] on pager mention explicitly that page argument needs to be passed to search

[ddeboer]

• [ ] document result.total for m_search

[ddeboer]

• [x] mention {% debug %} in Templates
• [ ] z_db usage and params
• [ ] a logging chapter (we now only have mod_logging): how to write log messages to /admin/log
• [ ] sanitize_embed_url notification
• [ ] link to search types from the Search chapter

[mmzeeman]

mod_search is missing documentation on the search result. It has a number of properties which are very useful.