Re: [mh] documentation rework

[Michael S. <mi...@st...>]

One thing that I find particularly confusing in any open source project is
that "best practices" change over time but the code base and documentation
is not reworked to match.  At the same time the best practices are rarely
documented.  This makes it very hard for a new developer to understand how
they should approach particular problems.  Documentation is one category
that definitely fits this issue.
How about starting this process by using the wiki to document the "best
practices" for documentation?  Then at a minimum new code can reflect the
best practices.
Count me in helping with any of the work below.  Just divide it up onto
discrete tasks and point me at one.

-----Original Message-----
From: Rick Bolen (GM) [mailto:ric...@gm...] 
Sent: Saturday, April 10, 2010 8:12 AM
To: The main list for the MisterHouse home automation program
Subject: Re: [mh] documentation rework

David Norwood wrote:
> Some of Marc's comments on the podcast re-emphasized for me the 
> importance of reworking the misterhouse documentation.  The 
> documentation consists of the wiki, the mh/doc directory in the 
> distribution and svn, and in the scripts and modules themselves.  
> There is definitely a place for all three of these types of 
> documentation, but I would like to see some changes and look for input 
> from the community.  I think the mh/doc directory should contain 
> reference documentation about scripts and modules, and the wiki should 
> contain how-to information and other user orientated material. 
>  
> To this end, I recommend the following changes:
>  
> - Move some of the information that is better suited to the wiki out 
> of the mh/docs directory.  This includes most of the html files in 
> that directory.  Hopefully, this will inspire users to keep them up to 
> date.  
I'm concerned that this could lead to more spead-out and diffuse 
documentation. I agree that the wiki is more suitable for some types of 
info, but I think some of this info could\should be duplicated in (or 
derived from) POD - with exception of case specific implementations, 
details, and discoveries.
>  
> - Create a script that checks for updates to pod files in mh/docs and 
> regenerates the html files (possibly outside the mh hierarchy) so svn 
> users get updated reference material. 
>  
I just re-read Damien Conway's "Documentation" chapter (15 pages) from 
"Perl Best Practices" [O'Reilly]. In my opinion, MH, as a project, is 
way overdue for "consistency conventions" that aid maintainability. The 
code side of things have matured a bit more than the documentation side. 
Conway's analysis and recommendations are sound, and I'd be happy to 
use\implement them, but I'm not against other ideas as well.

He mildly argues for keeping POD documentation in code files, and not 
separate POD files (they inevitably get out of sync). He also recommends 
utilizing perldoc tagging\markup conventions to separate user 
documentation from technical documentation.

> - Try to standardize on pod format in mh/docs and make sure everything 
> is linked from someplace else.  Many of the files in mh/docs are 
> orphans.  
Agree, as I mention above.
>  
> - Move the module documentation out of mh/docs/mh.pod file to the 
> actual pm files in the mh/lib directory (a la CPAN).  Many modules 
> don't have any documentation or have out of date documentation.  This 
> will encourage developers to document modules.  
>  
Yes, but could we compile some of the user documentation from the 
embedded "user doc" pod documentation?
> - Create a script to check for module updates and extracts the 
> documentation and generates an items.pod, or just links to the pm file 
> with perldoc.  I haven't researched this enough yet.  Do we use 
> perldoc or another script?  How do we handle module files with 
> multiple packages?  
>  
I guess this is where I was headed with the previous comment.
> - Perhaps we should move some of the other documentation (like for 
> global variables and functions) out of the pod files and into the 
> actual scripts where they exist.  The idea here is it is more likely 
> the documentation will be more up to date if it's close to the source 
> code.  Does anyone know if there is a performance hit including 
> documentation in-line?  
>  
I'd say that whatever is considered the default core 
download\install\execution of MH should documented as MH (with a 
referencing of the core modules\scripts). Then any added globals etc. 
should be documented in their respective modules\scripts.
> - Create an items.xml file that contains all the information required 
> by read_table_A.pl, read_table_xml.pl, and the item editor web 
> interface.  Currently, it's a pain to add support for new items to 
> these scripts and often only read_table_A.pl gets updated.  This 
> should make it easier add new items and improve the documentation of 
> items.  
I don't know enough about this yet to comment.
>  
> I realized writing this that the term "item" used in misterhouse is a 
> little confusing.  An item in misterhouse is basically a perl package 
> that has a constructor like "new".
>  
> Please comment on my task list and let me know if you are willing to 
> work on any of them.  Some of the tasks don't require any programming.  
I'm willing to help on all of this.
>  
> David
>  

----------------------------------------------------------------------------
--
Download Intel® Parallel Studio Eval
Try the new software tools for yourself. Speed compiling, find bugs
proactively, and fine-tune applications for parallel performance.
See why Intel Parallel Studio got high marks during beta.
http://p.sf.net/sfu/intel-sw-dev
________________________________________________________
To unsubscribe from this list, go to:
http://sourceforge.net/mail/?group_id=1365