User Documentation Tasks

[mstovenour]

Feel free to work on any of these issues if you feel so inclined. Make sure you understand the MisterHouse documentation "classes" and how each is maintained before working on the documents. See Maintaining MisterHouse Documentation. If you have any questions don't hesitate to ask on the MisterHouse Users.

• docs/intro.html -- Windows versions >= XP, links to SVN, Contact email should be mail list not Bruce, resolve Lieven's concern
• docs/features.html -- could use lots of updates... at least remove/fix any broken links
• docs/download.pod -- need to add target="_blank" to <a> for GitHub. https will not open in frame
• docs/install.pod -- Windows versions >= XP; change to FHS file layout?; other updates?
• docs/mh.pod -- Windows versions >= XP
• docs/faq.pod -- Windows versions >= XP, delete references to compiled version, ...
• docs/updates.pod -- delete content and change so it links to GitHub changes log
• docs/examples.html -- Need to point links to git hub source
• `docs/examples.txt -- Some of these descriptions are probably not current
• docs/maillist.html -- Links don't like to open in captive frame, <a> needs to include target="_blank"; might delete link to IRC channel
• docs/usage.html -- this is a dynamic usage map that is no longer maintained. delete?
• docs/authors.html -- Very old. Would be cool to automate from GitHub with a script. delete?
• Need to consider how to update the "last modified" dates at the bottom of the .pod/.html pages. Otherwise might delete the dates; but as a user of other opensource projects I think it is useful when I can see a last update date.
• Web UI Documentation: Button web/ia5/house/main.shtml line 56 has wrong link for sourceforge mail lists. Should be: http://sourceforge.net/p/misterhouse/mailman/misterhouse-users/

[krkeegan]

docs/usage.html - I vote delete it and all related pages (including the user list with names and cities of users). If we want something like this we could add some sort of tracking script to the online documents and make the stats public. However this would be complicated as such a script CANNOT be allowed to run on user's local machines. Plus why do we need this at all?

[krkeegan]

docs/authors.html - I created an Ohloh.net entry a while back, it creates a similar list although the numbers are not the same as much of Bruce's work is left out as it predates any version tracking. You can view the ohloh thing at:

https://www.ohloh.net/p/misterhouse/contributors?query=&sort=commits

Github also provides a nice look too:

https://github.com/hollie/misterhouse/graphs/contributors

[mstovenour]

I'm ok with deleting docs/usage.html. While I think it is cool, it is just too creepy these days. Although, having MisterHouse report my location is probably the least of my privacy concerns. I think this could only be useful if it is a voluntary button (i.e. "Tell the world you use MisterHouse!"). And even then someone would need to volunteer to build the tracking / mapping. I vote to remove support....

[krkeegan]

Fixing docs/install.pod will require a bit of a vote as to what is the prefered installation structure. Beyond that, I am in favor of a FHS layout.

I also think a windows user should edit this, I have no idea what the current/best form of perl (ActiveState?) is for windows.

[mstovenour]

I've already modified the windows content but it could use more I'm sure. I run both environments; most testing is on Windows; production on Debian. As for voting on the recommended file system layout, I think those of us that support users on the mail list get a voice. Ideally we would just have an install script that built it the way we want but that might give more sophisticated users the ability to override.

[hollie]

Concerning the recommended installation structure: my vote is for keeping a structure that easily allows you to keep multiple versions of the MisterHouse 'software package' next to each other, all making use of the same user settings. This way you can easily test out proposed changes by other users.

Is this possible with the proposed FHS layout? (Disclaimer: I'm no specialist, just curious). My MisterHouse installation is in a folder on a user account that contains the 'code' with my customizations, a subfolder that contains that master clone, and one subfolder that contains a clone that I use to test out pull requests.

[mstovenour]

It can get complicated if we want to be strictly FHS compliant; run time files in /usr/bin, config in /etc, logs in /var/log, pid files in /var/run, etc.

At a minimum we could separate the structure into read/write and read-only sections. In that case the read-only installation source should go in /usr (I use /usr/local/mh) and the runtime directory would go in /var/ (I use /var/local/mh but /var/mh is good too). Ideally the install would support the ability to mount /usr read-only. Backing up /var and /etc should get "all" configuration and data files.

Maybe the ideal scenario is to provide an install script that requires two directories as input options (one for RW data one for RO files). Another option on the install could be to provide for full FHS compliance. Users are then free to put the two directories where ever they wish but we guarantee a separation.

[krkeegan]

RE the last "update dates." These look like simple javascript calls to check the file modification date. Are these not working for some?

[mstovenour]

RE: "last modified" dates
Kevin I just assumed the dates were statically written the last time the HTML files were manually updated. I didn't know exactly how it was done and just assumed it would need a different process. If you think the dates are being updated correctly then lets drop this one off the list.

[krkeegan]

They are currently generated using JavaScript and the modified date of the
file.

However, I just realized that this probably won't work, git doesn't track
file dates, so the date for new users would likely be their install date.

I agree it would be nice to have this work, but if it isn't automated it
will never be right. My only solution is to include the release version in
the page footers. It won't tell you when that particular page was changed,
but at least you will know you have the most current version of that page.
On Jan 18, 2014 9:29 AM, "Michael Stovenour" [email protected]
wrote:

RE: "last modified" dates
Kevin I just assumed the dates were statically written the last time the
HTML files were manually updated. I didn't know exactly how it was done and
just assumed it would need a different process. If you think the dates are
being updated correctly then lets drop this one off the list.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/339#issuecomment-32687297
.

[krkeegan]

I am closing this, I think I covered all of the issues specifically identified by @mstovenour, with the exception of the last modified date on the pod->html pages. I do not have an immediate solution for this problem because git doesn't respect file dates. To clean up the issue tracker, I am going to start a new issue for this.