For documentation, we encourage contributions to Zotonic from the community even more!
We use git for documentation. For large documentation changes you should take the same approach as with Contributing source code: e.g. create a fork of Zotonic, create a topic branch, make the changes, push, pull request.
However, for small changes, typos, et cetera, Github provides a nice edit button which you can use to edit these .rst files.
Under Actions in the sidebar, there is a View source link directly to the ReST source for the current page on github.
Emacs’ rst-mode does the job for most things. It has nice coloring and indenting. Paragraphs are hard-wrapped at 80 characters with single newlines.
Use the following convention for headings:
First-level heading =================== Second-level heading -------------------- Third-level heading ...................
When writing documentation of modules, actions, etc.; anything under ref/; the first level heading is already there for you, generated in the meta-*.rst file. So you should only use ---------- and .......... for the headings in the ref/ files.
When using Emacs, this little snippet helps with adding underlines to headings:
(defun underline-with-char (char) (interactive (list (read-from-minibuffer "Char: "))) (when (= 0 (length char)) (error "Need a character")) (setq char (aref char 0)) ; Ignore everything but the first char. (save-excursion (goto-char (point-at-eol)) (insert "\n" (make-string (- (point-at-eol) (point-at-bol)) char))))
From a mailing list post.
Be generous with using references (:ref:`pagelabel`) in your writing. The more terms are linked to their respective documentation pages, the better. Only make the first occurrence of a term a reference to its page, though; consequent occurrences can be made `italic`.
Add a .. seealso:: section at the bottom to highlight any other pages which are closely related to the current one, for example:
.. seealso:: :ref:`dev-contributing`
For the easy editing of tables, we use Emacs’ table-mode, which at first has a bit of a learning curve but actually works pretty well when creating the ascii-art tables that the RST format requires you to use.
In general, we use this style of table:
+--------------------+-------------------+ | Header |Other header | +====================+===================+ |This is the table |Some more contents | |cell contents | | +--------------------+-------------------+
A Zotonic Cookbook item is a single-concept solution to a well-defined problem, living in the Cookbooks section of the documentation.
Useful items range from the simplest content management tasks to technically sophisticated module development and site administration solutions. This means that items are welcomed from noobies and wizards alike.
Whenever you struggle to find a solution to a specific problem, fail to find a Cookbook item that addresses it, and work through the solution with a final “Aha!,” you have the raw material for an excellent Cookbook submission.
A well-written item has four sections:
WHY: What problem does this Cookbook item solve? What benefits does it deliver?
Four major reasons for submitting Cookbook items are:
ASSUMPTIONS: What does this item assume about operating system, Linux distribution, programming skills, knowledge of Zotonic architecture and conventions etc.
HOW: Step-by-step instructions for implementing your solution.
Don’t take user competency for granted. When you specify a command, note what user name you’re working under and what directory you are working in. Respect the noobies by including steps that may be obvious to you but not so obvious to folks with less experience.
Think of your instructions as a check-list. A noobie should be able to achieve success by reading, implementing and checking off each instruction. Keep your instructions simple, complete, and clear.
Recruit a noobie to try out your solution. Fix the stumbling blocks s/he encounters. If you can’t find a noobie, put yourself in noobie mind. Remember, you too once were one.
Basically, there are two kinds of quotes. There are “curly quotes” and “straight quotes”.
In text we use the curly quotes and not the non-curly quotes, as the non-curly ones are really inch marks.
If a programmatic value is described then use two back-ticks, to make the text fixed width. So something like: if else and not “if else”, or “if else”.
Same holds for the ’ in words like it’s, that is a curly one, and not a foot.
Use ‘ (foot) and ” (inch) in programming texts, as that is what is used in the programming language.