Geant 4 Documentation Geant 4 Workshop 4 October

Geant 4 Documentation Geant 4 Workshop 4 October 2002 Dennis Wright • Internal documentation review • Documentation improvements • Plans for future improvements 1

Internal Review of Documentation • Recommendation 4. 5 of review panel (June 2001): Periodically review and update documentation • Sept. 2001 – internal review begun • Focus on re-organization, missing material, physics, readability and maintainability • committees assigned to each major manual • recommendations due by Nov. 2001 for inclusion into December release • Detailed review begun Jan. 2002 focusing on updating figures, improving English, checking references, …. 2

Results of the Review (1) • Maintain overall documentation tree structure – Introduction to Geant 4 – Installation Guide – Application Developers Guide – Toolkit Developers Guide – Physics Reference Manual – Software Reference Manual • Problems with above structure – Some duplication remains, maintenance difficulties 3

Results of the Review (2) • Improve English throughout • Many explanations unclear or too brief • Missing sections • Review/update references and links • Poor continuity (text by many authors) • List contact person or author for each section • Figure style should be consistent throughout • Reduce duplication of material 4

Documentation Improvements (1) • Introduction to Geant 4 – Completely re-written (taken largely from Geant 4 general NIM paper) – Aimed at a less technical level – Separated FAQs into their own document • Installation Guide – Explanations expanded, clarified – Attempted to make guide more self-consistent without duplicating too much of other manuals – Added links to release notes, specific build procedures which are updated with each release 5

Documentation Improvements (2) • Application Developers Guide – Completely re-organized • Duplicated material removed • More logical grouping of topics • More chapters, fewer sub-headings – easier to read – – – New introduction Several missing sections filled in – more to come More material added to existing sections English revision 50% complete Links repaired and updated 6

Documentation Improvements (3) • Toolkit Developers Guide – Figure uniformity is being imposed – change to Rose UML about 25% complete (action item for category coordinators) – English revision 30% complete – Material added to some sections, other sections still missing – Links repaired and updated 7

Documentation Improvements (4) • Physics Reference Manual – New introduction added (scope and purpose, some definitions) – Some duplicate material removed – Many incorrect references, links fixed and updated – Some missing sections filled in – English revision 33% complete – Roughly 50% of reviewers’ detailed suggestions implemented by authors 8

Administration • New policy: no new feature or major change of the code will be included in a release until documentation is provided – Documentation coordinator will inform release coordinator 2 weeks before release – Largely successful – only a few exceptions • Maintenance: – As volume of documentation increases, keeping it up-todate and consistent becomes more difficult – Future re-organization of documents may be required • Complaints about too many documents, duplication 9

Plans and Ideas for 2002/2003 • Complete all recommendations from internal documentation review • Documentation sub-committee (HPW, PA, DB, DW) met briefly in the spring to consider new “Models Manual” – Outcome: models manual not necessary – distribute material to existing documents – Options: • new addition to Application Developers’ Guide: section on example (“best guess”) physics lists • new addition to Physics Reference Manual: catalogue of physics processes and models 10

Plans and Ideas for 2002/2003 • • Create an index for Physics Reference Manual Same for Application Developers Guide New analysis manual Web presentation upgrade 11

Web Presentation Upgrade • Recommendation 5. 1 of external review panel: – Periodic review and update of web pages • Internal review process began in Spring 2002 – E-mail to TSB members soliciting comments – Preliminary overhaul plan drawn up, circulated to TSB – Discuss plans at collaboration meeting 12

Comments on Current Web Pages • Main page is too dense, too many links • Outdated appearance – modernize • Navigation is confusing • More pictures (like the front page poster) 13

Proposed Changes to Web Pages (1) • Main page – make it simple – Welcome statement – One introductory paragraph explaining G 4 – Only a few (~7) navigation links: • • News (prominently featured with 3 latest items) User forum Results and publications Organization Search Documentation User Support – Keep main page short (no scrolling) – Use bigger fonts 14

Proposed Changes to Web Pages (2) • Subsidiary pages – Enforce identical formats for all second-level pages (already done in most cases) • Same format as main page • Third-level pages may vary – Use two-column format where possible – Use redundant links – for topics which don’t fit cleanly into top 7 categories, and to ease navigation – Bigger fonts here too 15

Proposed Changes to Web Pages (3) • More links to satellite Geant 4 and external web sites • Fix broken links (as always) 16

Conclusions (1) • State of the documentation: – Introduction to G 4, Installation Guide, Application Developers Guide in good shape – Toolkit Developers Manual needs lots of work – Many reviewer comments for Physics Reference Manual must still be implemented – Software Reference Manual was unchanged (not included in review) 17

Conclusions (2) • “No documentation – no code” policy seems to be working, but a few leaks need to be plugged • Document management is becoming a bigger job – Documentation is currently not bad, but could be a lot better – Many new ideas for improvement – the documentation coordinator needs more help 18

Conclusions (3) • Initial web refurbishing plan ready – refine and detail – time to allocate labor to the task 19