Updating the Documentation

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. This page is a living document and will be updated frequently until the developer community reaches consensus regarding the best way to manage each of the document classes.

Table of Contents Motivation Documentation Classes User Documentation ManPage Files User Documentation Of mh.ini parameters and common code files User Contributed Documentation Developer Documentation Maintaining The Documentation User Documentation ManPage Files User Documentation Of mh.ini parameters and common code files User Contributed Documentation Developer Documentation

Motivation

Below is a broad categorization of for classes of documentation available. 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 while supporting and encouraging community contributed documentation that may not be as accurate or current
• Provide in-application user documentation
• 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/ia5/index.shtml 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// documentation and should be the most accurate / stable.

User Documentation Of 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.

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 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.
3. A smidgen of developer documentation

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, http://localhost:8080/docs/modules.html, http://localhost:8080/docs/items.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:

1. Is made available both on the Internet and locally in every copy of MisterHouse
2. Can only be updated by the core MisterHouse developers

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. Contributions to this documentation will generally be permitted in the same manner as

• Github publishing docs Github docs and publish to SF (WIP)

User Documentation Of mh.ini parameters and common code files

The rules for maintaining this documentation is documented in Documentation Best Practices and is hard coded into the MisterHouse code.

User Contributed Documentation

User contributed documentation is maintained on the misterhouse.wikispaces.com wiki. 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.