> >
> > 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.
Agreed. For it to work, it needs to be backward compatible with perldoc,
and intially needs to be *really* minimal.
I like the idea of auto-emailing the module authors a url to their
p5eedoc - they may get to like it!
That's the first stage. But then as things develop I think the p5eedoc
utility should help *encourage* p5ee coding standards, syntax conventions
etc.
>
> 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.
>
Agreed.
'Enforce' may be too strong a word - but there does need to be a way for
the p5ee 'standards' to propagate - and I think the documentation tool
can do it - but from the outset it needs to apply the 'stamp' of p5ee.
> > 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.
>
Hmmm ... agreed. I think a simple perldoc->p5eedoc translator
should happen first - that uses perldoc and source parsing to create the
documentation - it needs to be really minimal.
> > 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.
>
Cool.
> > * 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.
>
Yes, But I think the road could start with the p5eedoc
translator/documenter.
Ideally I'm thinking of a command line tool that will 'bless' a
module as p5ee.
NIgel
--
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.
