1 TeraGrid Documentation 2006 TeraGrid Documentation 2006 and Beyond Diana Diehl 3/09/2006 San Diego Supercomputer Center Documentation Group

2 TeraGrid Documentation 2006 Topics in this presentation Motivation for change Growth of Ultimate objectives Specific goals TeraGrid documentation family Focus aAreas User Info User Info section re-org User Info new features Knowledge base Portal TeraGrid User News Ongoing maintenance & growth New TeraGrid site design Future development Challenges Solutions

3 TeraGrid Documentation 2006 Motivation for Change Outreach to new communities –New compute and data resource users –Greater range of preferences in information retrieval Growth of the TeraGrid infrastructure –Increased complexity, heterogeneity –More RP sites and resources –Changes in functionality, more options New focus on customer service –Emphasis on faster drill-down –Need for more contemporary information delivery

4 TeraGrid Documentation 2006 Motivation specifics User Survey –Difficulty with finding info –Call for new features –Frustration with contradictory info on RP and central site NSF recommendations—we’re on the same page! – A distinct Getting Started Guide/primer – More online training material to augment meetings – Providing ways for users to help each other – Substantial improvements and enhancements to existing docs – Copious online examples – Equivalent quality, structure and content across components of TeraGrid – Centralized, cohesive documentation with centralization of both version and URL control, which is essential to ensure the usability of the documentation

5 TeraGrid Documentation 2006 Growth of Sept. FY04: 4292 unique visitors Sept. FY05: 11,200 unique visitors (entire site); does not include news.teragrid.org; accounts.teragrid.org; software repository; stats exclude bots and search engineswww.teragrid.org 70, Oct-05 20, Jan Aug-03 wordspages KBDate The old one-page Getting Started Guide Model just doesn’t fit any more

6 TeraGrid Documentation 2006 Ultimate objectives 1.Improve customer service for all users 2.Lower the barrier of entry for new communities 3.Improve ease of information management for staff

7 TeraGrid Documentation 2006 Specific Goals Each project or task should accomplish one of these: Expose most used features Make detailed information easier to find Improve accuracy Expand user choices Simplify/clarify complexity Reduce redundancy Optimize the site infrastructure Add new information Make maintenance easier Strengthen the reputation of TG

8 TeraGrid Documentation 2006 TeraGrid User Documentation Family Sites that contain related or duplicated information userinfo Resources Access Jobs Data Sub-domain Web sites User news Accounting Monitor pages Software database Knowledge base TG Portal RP site Web sites User Guides Other tools Related sites POPS/CI- Partnership

9 TeraGrid Documentation 2006 Example of duplication: Compute resources Knowledge base TG Portal POPS CI-Partnership RP site Web sites

10 TeraGrid Documentation 2006 Focus areas for 2006 External –User Info upgrade –Interaction with knowledge base –Interaction with portal –TeraGrid news –New logo and style –Interaction with RP sites –Ongoing maintenance Internal: –User Services tools –TeraGrid conference

11 TeraGrid Documentation 2006 Make existing content more usable Add new content & better delivery = overhaul!

12 TeraGrid Documentation 2006 Tasks: Section Re-org Rethink all sections Make overview pages more informative Consolidate site-based code/script examples Improve navigation mechanism to better accommodate the rapidly expanding volume of content on the site Highlight preferred methods

13 TeraGrid Documentation 2006 New/Improved Features 1.True Getting Started Guide: “pocket guide to TG” for new users 2.Customizable resource pages: users choose views  easier comparisons & filtered views 3.New top User Info page: expose most needed info  quicker drill down. 4.Printable, customizable guides: DB delivery of site content 5.Expanded Tutorials section

14 TeraGrid Documentation 2006 Top User Info Page  a useful tool Expose most needed info—quicker drill-down TG Portal User news Tutorials Help Desk Add User Form Reservations Machine status Knowledge base Software library Links to RP sites Acknowledgement boilerplate Community software requests From text-based site map to featured content

15 TeraGrid Documentation 2006 Ongoing maintenance & growth Continue to add new documentation as required –Universal Remote? –Global gxmap –tgcp –Globus 4/Web services –Updated RP site specs

16 TeraGrid Documentation 2006 New method for documentation Quick drill-down Selected subject matter Succinct, specific articles Free text search of select content vs. Hierarchical page search of *all* content Free text search of select content vs. Hierarchical page search of *all* content

17 TeraGrid Documentation 2006 User Info Integration Tasks Contribute content: break knowledge into short, specific articles based on user questions and existing documentation Review KB articles Hyperlink KB articles back to detailed User Info Make KB accessible from every User Info page Create complementary style to clearly brand KB and let users know where they are at all times Define workflow to keep KB and UI in sync

18 TeraGrid Documentation 2006 User Info integration tasks Share common info—not duplicate: Integration of content and forms Document recommended use of portal Refer new users to portal at top level of site Document bugs and idiosyncrasies as portal evolves Make portal accessible from every page Promote portal within appropriate sections of site (access, DN propagation, batch jobs, checking resource loads and queues)

19 TeraGrid Documentation 2006 Application Redesign New application program with robust database backend New display front end New categories to improve service to user communities Integration with Inca Enhanced delivery features

20 TeraGrid Documentation 2006 New program—new DB backend Increase functionality & improve display Populate new user subscribers from source database Improve reliability; fewer points of failure Add record-based locking  no more corruption and overwriting of the subscription flat files Enable dynamic display of select news from home page, EOT page, and others

21 TeraGrid Documentation 2006 New front end display Better category sorting Display by event date (i.e., more sensible announcement order) No more archive page  user-customizable filters Calendar-based event and news display

22 TeraGrid Documentation 2006 Enhancements & Increased Functionality New downtime events feature to integrate with Inca New categories to improve service to user communities  –Separate out networking –Integrate media news with user news –Management-controlled critical news category (users can’t unsubscribe to this—security events) –Education category Filterable tags in subject lines  –Allow client filtering by users receiving User News by RSS Feeds  –Increase choices for users for method of delivery

23 TeraGrid Documentation 2006 Look, Feel, and Usability Work with ER and new Web coordinator to implement site-wide changes –New logo and colors –New navigation –New layout –TeraGrid site standards –Resolve navigation conflicts

24 TeraGrid Documentation 2006 Future Development External –Move general content to DB –Incorporate Cyberinfrastructure glossary application New users can find any term or acronym –Universal Feedback All users can provide input from any User Info page –Digests of detailed info Known issues Tips Code samples –User Forum (in works at forums.teragrid.org) Internal –Web stats for quick reference –Enhancements to User Services log application –Integration of PI/ASTA log with TGCDB (populate automatically after XRAC meeting)

25 TeraGrid Documentation 2006 Challenges Platform heterogeneity  exception-driven docs complicates Getting Started Guide Complexity of system  high barrier of entry for new user communities Unclear communication pipeline  outdated content Multiple information delivery vehicles (portal, KB, User Info, RP sites)  difficult synchronization Distributed documentation  user confusion

26 TeraGrid Documentation 2006 Solutions Cycle of accountability –Point-of-contact at each RP site responsible for regular review of docs & approval of content –Mailing list/group where changes to RP info are distributed on a schedule Time/More FTE ER/Web coordinator (in the works!) Plan/Agreement to pull reusable content from database Break down complex info into digestible pieces through KB & rewriting User Info content

27 TeraGrid Documentation 2006 Current Priorities User Info top page Software overview re-design Hardware resources section  DB Getting Started Guide User News Maintenance: Portal, CTSS 3/Globus 4/Web services TeraGrid Conference & ER portion of site until Web coordinator named Knowledge Base