Maintaining MisterHouse Documentation

So you want to help with the documentation? Excellent. Please read the following so that you might understand how the documentation is organized, updated, and maintained. There are four classes of documentation for MisterHouse. This page defines these classes, the intended audience for each, and the process used to update that documentation.

For the impatient I've provided a quick summary that describes how to update each documentation category:

• User Documentation ManPage Files - In source repository docs/ directory. See Release process of a new stable release for instructions on updating SourceForge
• INI File and Common Code Documentation
• User Contributed Documentation - [Wikispaces Wiki] (http://misterhouse.wikispaces.com/home)
• Developer Documentation - This GitHub Wiki

Motivation for Separate Classes

Below is a broad categorization of for classes of documentation in MisterHouse. Each of these has a unique purpose, audience, and unique content. The reason for separate classes is to:

• Separate true developer documentation from user documentation: This is to keep from over whelming new users with work in progress code discussions and modules. The current wiki is a mixture of these and it can be quite intimidating at times to understand where the user documentation stops and the developer documentation starts.
• Provide stable well controlled user documentation with source control while supporting and encouraging community contributed documentation that may not be as accurate or current on a wiki
• Provide access to the user documentation from inside the application
• Make maintaining the documentation easy

Documentation Classes

User Documentation ManPage Files

This is the documentation currently at http://misterhouse.sourceforge.net (and redirected by http://misterhouse.net). This documentation is also included in the source; so you can point your browser at: http://localhost:8080/docs/ to see it. This documentation is aimed at the new user for installation and writing the user's own code. For the most part this is not developer documentation. This is the projects official user documentation and should be the most accurate / stable.

User Documentation for mh.ini parameters and common code files

This documentation is embedded directly in the mh.ini and common code files. This documentation is accessed from the web interface when editing the MisterHouse ini file or enabling common code files.

User Contributed Documentation

This is the documentation currently at http://misterhouse.wikispaces.com/. There are roughly three types of documentation here but users are free to add any documentation they like.

1. User contributed documentation for user related tasks like how to enable some particular device
2. User contributed "how to" recipes for compound tasks
3. User contributed corrections and special cases for the installation process. Hopefully as this type of information is collected by users, a developer will incorporated the changes in the official guides and then delete the wiki page.

Developer Documentation

This is mostly POD comments in the code. David Norwood originally created a framework for adding this information into the core MisterHouse documentation. Other users have been adding POD to the existing files. There is a default MisterHouse trigger to generate the POD docs by running bin/update_docs. If that is running on your system you can see the docs here: http://localhost:8080/docs/objects.html. In addition some of us have attempted to document various aspects of MisterHouse as we've discovered them. This documentation is in the Wikispaces wiki and recently also in the GitHub wiki. Generally there isn't much of this type of documentation.

Maintaining The Documentation

User Documentation ManPage Files

The user documentation is the most complex to maintain. This is because it is:

• Made available both on the Internet and locally in every copy of MisterHouse
• Changes can only be approved by the core MisterHouse developers, although anyone can submit a pull request

The latter is necessary to ensure the primary user documentation remains stable as users come and go that otherwise desire to update the documentation but that might not finish the job. The source for this documentation exists in the docs/ directory of the source files. Contributions to this documentation will be performed in the same manner as code updates (i.e. fork code repository, make changes to docs/ directory, create pull request). Once the source repository is updated, documentation updates can be published to SourceForge using the steps described in Release process of a new stable release.

User Documentation of mh.ini parameters and common code files

The rules for maintaining this documentation is is hard coded into the MisterHouse code. See below for details:

INI File and Common Code Documentation

User Contributed Documentation

User contributed documentation is maintained on the MisterHouse.wikispaces.com wiki. Anyone can request a login on the MisterHouse mail list.

Developer Documentation

Developer documentation is currently fragmented between the GitHub Wiki and misterhouse.wikispaces.com wiki. Anyone can request a login to update either, just ask on the MisterHouse mail list. Going forward this type of documentation should be created on the GitHub Wiki.