Great documentation makes great projects, so of course we want Elgg to have high quality, up-to-date documentation. We'd love your help making that a reality.

Our vision

Documentation should help you get stuff done, so we're embarking on a full rewrite of our docs to optimize for that goal. When writing the new docs, we'll:

• Focus on common tasks
• Eliminate the blah-blah
• Write thorough, task-oriented articles
• Include plenty of copy-pasteable code samples

Currently, the bulk of Elgg's docs are hosted in MediaWiki. This has sufficed for some time, but suffers from several problems:

• Requires yet-another-login to contribute
• Goes out of date quickly
• Lacks an editorial/review process
• Does not support multiple branches
• Is an administrative burden to the core team:
  • Debugging is a pain
  • Susceptible to spam

We're solving these problems by moving the docs to main Elgg repo on GitHub, and using Sphinx to manage our docs. In addition to solving the above problems, this allows us to:

• Include more people in the documentation process
• Submit code and associated documentation in one pull request
• Maintain a branch of docs for each branch of Elgg
• Distribute the documentation in various formats (HTML, ePub, etc.)

The new docs currently live at http://docs.elgg.org/master/en/index.html. They are being updated directly from the GitHub repository every night, so any documentation-related changes made will go live within 24 hours.

Now instead of documentation happening in fits and starts, we can document Elgg continuously, as development happens.

How you can help

Port the existing documentation

There are a lot of docs on the wiki still. Transferring it all to the new format will be a big undertaking. Here's our recommended approach if you'd like to jump in:

• Pick a page or set of pages from the wiki at http://docs.elgg.org/
• Convert them to rST (search for some online or command-line tools to help)
• Edit the content according to the writing principles outlined above
• Submit a pull request to http://github.com/Elgg/Elgg
• Once your PR is accepted, mark that page as converted

To kick things off I decided to focus on the task people most commonly want help with (installation):

• Found all the docs related to installing Elgg and merged them into one article.
• Deleted the repeated admonitions to "check the requirements" since the requirements are right at the top of this new page
• Converted everything to rST and checked it in to Elgg
• Added this note to the top of each wiki page that I ported:

We're rewriting our docs. This page has been ported to github. Join the effort!

Include docs with your pull requests

We'll bug you for these if you forget. We expect you to bug us if we forget, too! Here are some different types of documentation we'll be looking for:

• API docs on classes, functions, views, etc.
• Developer guides for plugin authors
• Design docs for people who want to understand how your subsystem works, why it is designed the way it is, what tradeoffs were made, etc.
• Upgrade instructions for site admins and plugin authors migrating from an older release of Elgg

Not every pull request will require all these types of docs, but most will require at least one type.

Tell us about incomplete or out-of-date docs

If something is poorly, wrongly, or not-at-all documented, we consider that a bug just as if the problem were in the code itself. Report problems to GitHub or the feedback group.

Translation

We aren't planning on supporting translations officially right now, but if you're strongly interested in maintaining something, please let us know in the feedback group and we can discuss further.