Documentation Analysis and Proposal Jeff kern NRAO

CASA The Issue CASA has a large amount of existing documentation – CASA Guides – Cookbook – Inline Help – Design Documents – Twiki pages – “Anecdotal history” Finding current applicable documentation can be a challenge from the users perspective CASA Users Committee Face-to-Face2

CASA User Input Improve and curate better CASA documentation; a small number of well- maintained documents is preferable to many that are not maintained and become out of date. -CUC 2014 User Survey Responses : The most frequent topic in the free form responses …more detailed general documentation on how different algorithms work …more detailed toolkit manual The explain files for CASA tasks are woefully inadequate 2015 CASA Users Committee Face-to-Face3

CASA Information Sources 2015 CASA Users Committee Face-to-Face4 Users ForumCookbookCASA GuidesKnowledgebase Wksp (NRAO)Wksp (non-NRAO)HelpdeskInline HelpDeveloper 100% 50% 0% Somewhat Useful Not Useful Very Useful

CASA Types of Documentation User Facing – Best Practices – Theory of Operation – Implementation Parameterization – Algorithm details – Tool Documentation – Task Description – Planning Documents Developer Facing – Coding Standards – Class Documentation – Design Documents – Architecture 2015 CASA Users Committee Face-to-Face5

CASA User Facing Documentation Design Consolidate to three documentation repositories: – CASA Guides Best Practices Tutorial Approach – Inline Help Minimal usage help – CASA Doc Pages Task and tool details. Implementation Description 2015 CASA Users Committee Face-to-Face6

CASA CASA Guides Very popular, highly rated for usefulness – Implies: Leave them alone; but some changes for focus and maintenance. Repository of Observatory Recommended Best Practices Update per release is proving difficult to maintain (SUS responsibility) – ALMA: Update on rotating basis – VLA: Moving to few end-to-end plus more modular topic based approach Now being automatically regression tested, should prevent errors CASA Users Committee Face-to-Face7

CASA Inline Help Has become overgrown, too much information Downsize to bare minimum, designed to answer the question: What was that parameter name again? rather than: How does this task work? Remove examples, explanatory text etc CASA Users Committee Face-to-Face8

CASA CASA Doc Pages Refurbishment and revitalization of the cookbook: – Chapters give overview, theory of operation for the various operations. Presented by topic, stringing them together for reduction is described in the CASA guides. – Detail descriptions of tasks and tools go here. Lots of space for examples etc. Implemented as HTML tree – Distributed with each CASA version Doc(tClean) or similar launches the appropriate page in the users browser (from local copy) – Current version also maintained on web CASA Users Committee Face-to-Face9