OpenPegasus Documentation Discussion What should we change, what should we keep? KS OpenPegasus Developers Conference 27 September 2012

Document Types Today Design Documentation – Currently PEPS with some in bugs. User Documentation – Currently no single organization Readme’s, html docs, couple of PDFs in CVS FAQs, other things on WIKI API reference (from header files) (not published recently) Release Documentation – Currently PEP and Release notes Release status information on WIKI Releases themselves on web pages Feature Status Page Bugzilla – Our documentation successes. Training documentation – None today Documentation Media – Documents on OpenPegasus WEB server (ex. Peps) – WIKI – (probably not) – Documents and readme files in CVS – Bug database

Design Documents Purpose – Define Design/implementation for review – Record Design for later use in other documents – Document Functionality of OpenPegasus Implementation – PEPs as separate HTML documents Issues Today – PEPs are almost never used after approval – Review/approval movement of documents – Hard to access with no indexing – Does not give any overview of OpenPegasus Architecture, implementation just pieces – Require completing design before start next step (out approval process) Advantages – Good model for review (commenting in documents)

Design Documents Questions Do we want to keep the PEPs as a form of design document? Do we want to keep them as separate HTML documents? How can we make these documents more useful after they are approved?

Design Document Proposal Continue to use PEPs as design documentation – Same general format as today. Move to use the WIKI to organize PEPs – Index all peps on the WIKI in a table Index points to the html PEP on web or another wiki page with PEP Include #, Title, status, pointer, Peg version, type, short description Add new PEPs by first adding to the index on the wiki Allow PEPs to be written on either wiki or as HTML documents and uploaded to Docs for Review until we figure out which is best.

(Design Documents)Continued Force use of PEPs for anything that is functional extension Design voting process – Propose trying to use Bug as voting tool. Simpler than creating separate documents

User Documentation Objectives – Give client/provider developer information on Pegasus – Give Administrators information on pegasus administration – General overview of Pegasus architecture, structure for all users. Issues today – No clear documentation location Readmes, docs, wiki etc. API doc (not even published) – Many documents obsolete(admin guide)

Questions What do we want as forms for User Documentation in the future? How can we insure that user documentation is kept up-to-date? How can we insure that we produce user documentation that is complete?

User Docs - Proposal User Doc needs to have a single location – Propose WIKI as single point – Duplicate what we need in CVS User doc – Admininstrators Guide (For each system) On Wiki with copy in cvs More online help for adminstrators – API Reference Create from Doxygen with pointer from WIKI – Provider and Client Writers guides WIKI – Configuration information TBD – Architecture, overall OpenPegasus Documentation WIKI with pointers to PEPs.

Bugzilla No changes proposed except updating the bugzilla code and modify voting process Change voting so component is automatic driven from change state of bug – Note that we are not sure who could do this since it means playing with bugzilla itself.