On Thu, 2002-08-01 at 04:35, Nigel Hamilton wrote: > HI Aaron, > > Your documentation point I think is crucial. > > Adoption will depend on how quickly/easily/cleanly a developer can > incorporate P5ee modules. > > Java has the javadoc utility to generate HTML docs from Java > source which lets the developer walk the inheritance hierarchy - this > is a great way of getting a 'feel' for the OO design. It also makes classes > 'look' the same.
We are to some extent rehashing an old topic I just realized. This must indicate its it importance or at least a common point of interest among us. http:[EMAIL PROTECTED]/msg00558.html > > I noticed that the p5ee::Blue pages have javadoc-esque > documentation - for me this is a great leap forward to combining > individual CPAN modules into cohesive packages. > > Ideally developers should click through their p5ee package > documentation before resorting to CPAN. > > But the documentation system should be more ambitious than Javadoc. > I do think there is some merit to the path Javadoc took, but when I try to compare Perl to Java I have to remember that Java is a commerical product and created with that in mind. Perl was created with the mindset of getting things accomplished by system admins, the fact that it can now be used to generate revenue or enhance your companies ability to, is just a result of the effort not the focus like Java. > It should do more than just let a developer browse the > documentation, and make things looks cohesive - it should help 'enforce' > it. > > I hear screams of .... TMTOWTDI ... but read on ... > > Can I humbly suggest, for a module/class/package to bear the P5EE > mark it must be first 'compiled' with the documentation generator. > > It should also encourage/enforce: > Encourage the module author to follow a convention, but more ideally a system needs to be created that can take existing documentation and break into its parts and then put stubs in for the missing EE attributes and then members of the P5EE group can edit and revise the information via a browser and then once approved by the "doc-king" the revised documentation would be automatically emailed back to the module author. I don't envision anything that forces a module maintainer to modify their documentation as being effective in this community. P5EE is, in my mind, a resource for the best in class of modules and more glue to get you going then it is an enforcer. > 1. p5ee naming conventions > 2. p5ee syntax style > 3. a module is not P5EE 'certified' unless it compiles into peedoc Modules can be P5EE 'certified' if P5EE certified documentation is available, but it doesn't have to ship with the module, we would prefer it does, but I don't see it being easy to get every developer to buy into the P5EE concept at first. > 4. auto generated PDF documentation (for boardroom consumption) There are already several modules available that will turn POD into PDF so this would simply require our P5EE approved/certified docs be converted via a cron job or some automated system. > * 5. be used in conjunction with a web-based IDE (for code > editing, browsing, testing, publishing packages to/from > p5ee.org, cvs) > > The p5ee documentation 'compiler' could be released in versions > ... with the initial versions being very 'lite' - and then gradually > asserting the values/tenets of the P5EE mark - as adoption takes off > (fingers crossed). > At this point my "idea" doesn't go beyond standard pod tags. One thing that I think P5EE has to do before it goes beyond the current set of tools is prove the weakness of the existing ones. P5EE is about leveraging Perl in its present form to produce Enterprise grade applications. Everything one needs to do this already exists, what doesn't exist is a coding standard or a verification system that packages being used are relatively bug free and secure along with more aggressive regression testing of new module releases. But those topics are for down the road. > The web-based IDE could be a 'flagship' P5EE product - that > everyone gets by default when they download - also a great place for new > developers to dip their toes in. > > What do you think? > > NIgel > > > p.s. tabs can work in <textarea>s > > > Nigel Hamilton > > Turbo10 Metasearch Engine > > email: [EMAIL PROTECTED] > tel: +44 (0) 207 987 5460 > fax: +44 (0) 207 987 5468 > ________________________________________________________________________________ > http://turbo10.com Search Deeper. Browse Faster. > >
