I’ve stayed away from writing this email for many years. Mostly because I believe that if I have an opinion about improving something I should put up the time to get involved, but sadly I don’t have enough motivation to get involved in documentation work. That being said, against my better judgment, I’ll throw out a bit of history as I recall it (disclaimer) and offer some solutions that I think may have broad appeal to the list (maybe even Lieven J). If any of this is inflammatory, please accept my apologies; I didn’t intend that. That being said feel free to say STFU and I’ll go back to my selfish pursuit of Insteon support.
The documentation, well….. I think that Bruce Winter (the original MH developer) wrote most all of the “official” documentation. That is what you find on sourceforge.net (and redirected by misterhouse.net). Bruce still owns and maintains the misterhouse.net domain but as you can see it only forwards requests; I’m sure we can get him to forward that to any location and might even talk him out of the ownership if someone wants to pay the ICAN and DNS fees. Since Bruce there have been few if any attempts to keep the core documentation up to date; there has been an occasional attempt or two to add developer POD documentation for the code. One of us even made a big step forward in that area; but the user documentation is horribly out of date.
Here’s a broad categorization of the types of documentation available and some suggestions for each: Let me start by saying that I’m agnostic about “where” the documentation lives but I believe that someone needs to recreate/move “most all” of it from one of the three locations below if we are going to make a change. I do not think ignoring it all and starting over is the right thing to do as easy as it might sound because I believe will in fact make the problem worse.
First I’ll categorize the “types” of MH documentation, its purpose, and audience. There are currently three primary documentation sets each with a unique purpose:
1) User documentation: This is the documentation currently at http://misterhouse.sourceforge.net (and 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 (I say this with a big grin) be the most accurate / stable. This documentation is horribly out of date (circa 2005) but wouldn’t be that hard to clean up.
2) User “contributed” documentation: This is the documentation currently at http://misterhouse.wikispaces.com/. There are two types of documentation here: 1) user contributed documentation for user related tasks like how to enable some particular device; 2) a smidgen of developer documentation.
3) Developer documentation: This is mostly POD comments in the code. Like I said one of us made a lot of headway adding POD comments. There is a MH module to generate the POD docs. If that is running on your system you can see the docs here: http://localhost:8085/docs/objects.html, http://localhost:8085/docs/modules.html, http://localhost:8085/docs/items.html. In addition some of us have attempted to document various aspects of MH 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.
OK, what do we do with all this? I don’t think it is wise to attempt to throw it all out and start over. In addition there are few if any volunteers to improve it. What does that leave us with?
1) For official user documentation, this is included in the source and could stay there but needs a really good scrub if folks like Phil are going to have a better experience.
a. Maybe someone could volunteer to just delete all the horribly old and difficult to maintain parts (e.g. the release changes).
b. Maybe others could agree to be responsive to users on the mail list updating parts those users find wrong, misleading, or missing.
c. Maybe someone could figure out how to automate displaying this in the Github wiki? “That” would be a great win for the project. i.e. clean it up but keep most of it, keep it in the source tree so developers can easily modify it, and automating the web display.
I think this is in the spirit of Lieven's Github concept. This is also in the spirit of my concept where we move “most all” of a category and keep many excellent pages of documentation.
2) For user contributed documentation, I think we should leave this on a wiki with broad access so anyone (that isn’t a spammer) can contribute. It will be a mess, wikis always are but that is part of the wiki experience. There are some options here:
a. Leave it on wikispaces
b. Move it “all” to Github, however it needs to be clear where the “official” documentation ends and user contributed (i.e. suspect) documentation starts.
c. Either way maybe someone could volunteer to play editor and reorganize it a bit possibly tossing some of the oldest least accurate parts.
d. Regardless I do volunteer to rework the landing page to make this clear distinction of documentation locations and purpose once we all agree on the direction.
3) For the developer documentation, there is so little it shouldn’t be hard to consolidate it where ever we choose. It should be a combination of POD generated documentation and wiki for more general descriptions.
a. Maybe this is the single best use of the Github wiki. If we put the official project documentation 1) there as well, then it needs to be clear where the user docs stop and the developer docs start.
b. Maybe someone could figure out how to automate displaying this in the Github wiki?
In summary I’m not implying that we need 3 “locations” for documentation just that we have 3 separate “types” that should be clearly delineated to avoid confusion. I think where we keep each should be based on 1st on the altruism of someone willing to edit it and 2nd on the ease of maintaining it.
I believe we should address 1) above before looking at the others so newcomers like Phil will have a much easier time. I am very interested in a lively discussion on this topic especially by those that have in the past or will now volunteer to help out.
From: Marc MERLIN [mailto:email@example.com]
Sent: Sunday, February 24, 2013 9:18 AM
To: Eloy Paris
Subject: Re: [mh] Permissions to update sourceforge HTML pages
On Sun, Feb 24, 2013 at 08:29:55AM -0500, Eloy Paris wrote:
> We are not doing anyone a favor by maintaining documentation in two
> places so we need to decide where we are going to keep documentation and
> stick with it.
> Personally I do not have any preference but I tend to favor wikispaces
> because there is a lot of documentation there already. Unless, as
> Michael says, someone takes on the task of moving things from wikispaces
> to github.
I kind of agree that having docs in 3 places doesn't make sense.
Getting access to sf.net is "work" because you need an account and an
Getting access to wikispaces is easy, and lots of our docs are there, why
not keep that?
Github, I have nothing against, but I'm just not convinced that we need to
move docs there from wikispaces.
"A mouse is a device used to point at the xterm you want to type in" - A.S.R.
Microsoft is to operating systems ....
.... what McDonalds is to gourmet cooking
Home page: http://marc.merlins.org/
Everyone hates slow websites. So do we.
Make your web apps faster with AppDynamics
Download AppDynamics Lite for free today:
To unsubscribe from this list, go to: http://sourceforge.net/mail/?group_id=1365