New documentation should fit well with the rest of Elgg’s docs.
Elgg has a grunt script that automatically builds the docs, opens them in a browser window, and automatically reloads as you make changes (the reload takes just a few seconds). You need yarn and sphinx installed to be able to use these scripts.
cd path/to/elgg/ yarn grunt
It’s that easy! Grunt will continue running, watching the docs for changes and automatically rebuilding.
The current breakdown is not necessarily the One True Way to organize docs, but consistency is better than randomness.
This is everything that brand new users need to know (installation, features, license, etc.)
Guides for administrators. Task-oriented.
API guides for plugin developers. Cookbook-style. Example heavy. Code snippet heavy. Broken down by services (actions, i18n, routing, db, etc.). This should only discuss the public API and its behavior, not implementation details or reasoning.
Design docs for people who want to get a better understanding of how/why core is built the way it is. This should discuss internal implementation details of the various services, what tradeoffs were made, and the reasoning behind the final decision. Should be useful for people who want to contribute and for communication b/w core devs.
Contributors guides for the various ways people can participate in the project.
More detailed/meta/background information about the project (history, roadmap, etc.)
Elgg is not an acronym, so writing it in all caps (ELGG or E-LGG) is incorrect. Please don’t do this.
- In English, Elgg does not take an article when used as a noun. Here are some examples to emulate:
- “I’m using Elgg to run my website”
- “Install Elgg to get your community online”
- When used as an adjective, the article applies to the main noun, so you should use one. For example:
- “Go to the Elgg community website to get help.”
- “I built an Elgg-based network yesterday”
This advice may not apply in languages other than English.
Refer to the reader as “you.” Do not include yourself in the normal narrative.
When we’re done installing Elgg, we’ll look for some plugins!
When you’re done installing Elgg, look for some plugins!
To refer to yourself (avoid this if possible), use your name and write in the third person. This clarifies to future readers/editors whose opinions are being expressed.
I think the best way to do X is to use Y.
Evan thinks the best way to do X is to use Y.
elgg_register_jsfunction to register it.
elgg_register_jsto register it.
It is not easy to tell when a particular sentence or paragraph was written, so relative dates quickly become meaningless. Absolute dates also give the reader a good indication of whether a project has been abandoned, or whether some advice might be out of date.
Recently the foo was barred. Soon, the baz will be barred too.
Recently (as of September 2013), the foo was barred. The baz is expected to be barred by October 2013.
When you change documentation, remember to update the documentation translation templates before you commit:
cd docs/ make gettext
For more information, see http://sphinx-doc.org/latest/intl.html#translating-with-sphinx-intl