RSS

Bloggers

Brett Profitt
All posts
Twitter

Cash Costello
All posts
Twitter

Evan Winslow
All posts
Twitter

Juho Jaakkola
All posts
Twitter

Matt Beckett
All posts
Twitter

PaweĊ‚ Sroka
All posts
Twitter

Steve Clay
All posts
Twitter

Search

Blog tagcloud

    Aug
    24th
    by
    Evan Winslow

    Continuous Documentation

    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.