Documentation/Guidelines

Thank you for helping to improve Elgg's documentation! This page contains the official standards on how to write good documentation that is consistent in style with the rest of the docs on this wiki. Once you've read through this page, feel free to edit away to your heart's content. If you're not sure what to write about, you can check out the list of open documentation-related tickets and pick one of those.

Contents 1 Motivate the reader (but only briefly) 2 State your assumptions (but not all of them) 3 Keep examples consistent 4 Keep a consistent voice 5 Keep it up-to-date 6 Reuse, don't repeat 7 Get close to the code

Motivate the reader (but only briefly)

This is best done by giving a clear use case for is covered by the documentation that immediately follows. For the people who already know what they're trying to accomplish, this will serve to let them know if they're looking in the right place. For the people who are just perusing the documentation trying to learn about Elgg, this will help them get a vision of what kinds of things Elgg is good at accomplishing. It's important that this "motivation" be kept brief (one or two sentences) so the reader can quickly gauge whether that section is the right one for them.

State your assumptions (but not all of them)

Any necessary assumptions should be stated up front. If they aren't, there is a temptation to go on tangents explaining foundational concepts in the middle of the tutorial. This is distracting, often unnecessary, and makes (writing and reading) the tutorial more complicated that it has to be.

Keep examples consistent

Unless it's awkward to do so, you should stick with consistent examples when writing documentation.

• Always use http://localhost/elgg/ in your URLs. This keeps things consistent and makes it so that if a user is following your tutorial on their localhost, they could just click the link and be immediately taken to the right page, rather than typing in the url themselves.
• If you need an example plugin, always use "example" as the plugin ID.

Keep a consistent voice

Speak directly to the reader. Refer to them in the second person ("you"). If you ever need to refer to yourself, do so by name and in the third person. E.g., "Evan Winslow wrote some plugins that do X" is preferred over "I wrote some plugins that do X".

Keep it up-to-date

Documentation should be (re)written exclusively for the most recent version of Elgg. Any notes about differences b/w the present version and older version should be placed at the end of the document. This keeps you from constantly having to add parenthetical notes throughout the document, which detract from the clarity rather than add to helpfulness.

Reuse, don't repeat

If the documentation wants to provide an example, link to existing examples. Many code examples can be found in the Elgg source:

• http://code.elgg.org/elgg/trunk/documentation/examples
• https://github.com/Elgg/Elgg/tree/master/documentation/examples

If the doc assumes or requires understanding of a related but distinct aspect of Elgg, don't try to re-document that aspect of Elgg. Instead, link to the existing documentation. Doing so de-clutters the wiki and makes it much easier to keep everything up-to-date.

Get close to the code

Instead of documenting the core api on the wiki, do it right next to the relevant code in phpDoc style, and then we can use automated tools to build web-accessible reference documentation. This becomes a win for everyone, rather that a burden to upkeep.

jQuery and PHP are good examples of this kind of documentation in action.