From: David N. <dno...@ya...> - 2010-04-07 01:16:41
|
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. - 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. - 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. - 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. - 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? - 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? - 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 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. David |
From: Marc M. <ma...@me...> - 2010-04-08 03:25:10
|
On Tue, Apr 06, 2010 at 06:16:30PM -0700, 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. That would make sense. > - 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. Yes. Few people have svn access. It took me months to get it myself. > - 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. +1 > - 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? Not sure. > 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 happy to update the HAI code to put documentation in whatever format that would allow it to get auto-scraped and gathered somewhere else. Marc -- "A mouse is a device used to point at the xterm you want to type in" - A.S.R. Microsoft is to operating systems & security .... .... what McDonalds is to gourmet cooking Home page: http://marc.merlins.org/ |
From: Rick B. (GM) <ric...@gm...> - 2010-04-10 13:12:23
|
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 > |
From: Michael S. <mi...@st...> - 2010-04-10 13:52:15
|
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 |
From: David N. <dno...@ya...> - 2010-09-24 07:51:37
|
I finally got around to starting the documentation updates I threatened to make a few months ago. I wrote a script to convert pod documentation to html, and I also started the process of moving item and module documentation from mh.pod to the individual pm files. See the reasons in my original email. I also created a stylesheet for documentation files that roughly looks like the perldoc site: http://perldoc.perl.org/ Any input on the script or stylesheet would be appreciated. You can look at the documentation on my server at: http://judapeno.kicks-ass.net:8000/docs/mh.html#list_of_items_and_their_methods http://judapeno.kicks-ass.net:8000/docs//items.html Or just svn update and wait a day and the html will be updated on your server. The only item I have converted the documentation over so far is File_Item: http://judapeno.kicks-ass.net:8000/docs/lib/File_Item.html#file_item These are the other items that are currently documented in objects.pod, and need to have their documentation moved to the corresponding pm file: Generic_Item Group iButton_Item HVweb_Item IR_Item LCD Network_Item Process_Item RF_Item Serial_Item Weather_Item X10_Item X10_Appliance X10_Garage_Door; X10_IrrigationController; X10_Switchlinc; X10_Ote; X10_TempLinc X10_Sensor X10_Transmitter RCS_TX15 Socket_Item Text_Cmd Timer Voice_Cmd DSC_Alarm I would appreciate your help converting these items over. Just cut and paste the documentation from objects.pod into the corresponding pm file, and edit it using File_Item.pm as a guide. Of course, it would be great if you document any of the items or modules that need it. If you use svn, I recommend you set the html_alias_docs ini parameter to a directory outside the mh distribution tree. This will make it easier to manage any changes you make to Misterhouse. David From: David Norwood Sent: Tuesday, April 06, 2010 6:16 PM To: mis...@li... Subject: [mh] documentation rework 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. - 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. - 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. - 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. - 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? - 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? - 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 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. 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 |