- The Future of the Documentation Project


Published on

Published in: Economy & Finance, Technology
  • Be the first to comment

  • Be the first to like this

No Downloads
Total Views
On Slideshare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide - The Future of the Documentation Project

  1. 2. Present and Future of the Documentation Project Frank Peters Sun Microsystems Hamburg Documentation Project Co-Lead Clayton Cornell Sun Microsystems Hamburg Technical Writer
  2. 3. Agenda <ul><li> – The Present State </li></ul><ul><ul><li>User Access </li></ul></ul><ul><ul><li>Web Document Inventory </li></ul></ul><ul><ul><li>Issuezilla </li></ul></ul><ul><li> – The Future Vision </li></ul><ul><ul><li>High Level Objectives </li></ul></ul><ul><ul><li>Wiki Showcase </li></ul></ul><ul><ul><li>Next Steps </li></ul></ul><ul><ul><li>Challenges </li></ul></ul><ul><li>A Tribute to Gerry Singleton </li></ul>
  3. 4. <ul><li> </li></ul><ul><li>The Current State </li></ul>
  4. 5. User Access <ul><ul><li>Web page (traditional) </li></ul></ul><ul><ul><li>Wiki (growing) </li></ul></ul><ul><ul><li>Multiple routes, unclear information paths </li></ul></ul><ul><ul><li>Users have difficulties locating the information they look for </li></ul></ul><ul><ul><li>Search functionality on doc.oo.o is unsatisfactory </li></ul></ul> – the Current State
  5. 6. Web Document Inventory <ul><ul><li>Documentation webpages: CVS project “documentation/www” </li></ul></ul><ul><ul><li>Around 5,700 files in multiple subdirectories </li></ul></ul><ul><ul><li>Main problems with documents: </li></ul></ul><ul><ul><ul><li>Unspecified license </li></ul></ul></ul><ul><ul><ul><li>No source available </li></ul></ul></ul><ul><ul><ul><li>Of questionable relevance </li></ul></ul></ul><ul><ul><ul><li>Obviously outdated </li></ul></ul></ul><ul><ul><li>There is no general gate/house-keeper Areas with owner are in a better shape (eg oooauthors manuals) </li></ul></ul>See: – the Current State
  6. 7. Issuezilla <ul><ul><li>Issuezilla used for documentation planning and project management </li></ul></ul><ul><ul><li>The master issue list has a total of 151 issues, 129 ( 85% ) of which are owned by issues@documentation, i.e. no-one. </li></ul></ul><ul><ul><li>Suggestion: Abandon IZ as project planning tool </li></ul></ul> – the Current State
  7. 8. <ul><li> </li></ul><ul><li>The Future Vision </li></ul>
  8. 9. High Level Objectives <ul><ul><li>Create easy user access </li></ul></ul><ul><ul><li>Ensure targeted content </li></ul></ul><ul><ul><li>Ensure up-to-dateness and technical accuracy </li></ul></ul><ul><ul><li>Allow easy contribution </li></ul></ul><ul><ul><li>Minimize duplication of efforts </li></ul></ul><ul><ul><li>Implement transparent processes </li></ul></ul><ul><ul><li>Include all locales </li></ul></ul> – the Future Vision
  9. 10. Create Easy User Access <ul><ul><li>Establish as the portal for users to get documentation </li></ul></ul><ul><ul><li>Doc.oo.o does not necessarily need to host all the information, but route users to it </li></ul></ul><ul><ul><li>Reliability is crucial, users who fail several times will rarely return </li></ul></ul><ul><ul><li>BENEFIT: </li></ul></ul><ul><ul><li>Users find information quickly and don't get lost in content. </li></ul></ul> – the Future Vision
  10. 11. Ensure Targeted Content <ul><ul><li>Create user profiles to establish target audiences </li></ul></ul><ul><ul><li>Analyze existing content and categorize to audiences </li></ul></ul><ul><ul><li>Identify critical gaps and prioritize </li></ul></ul><ul><ul><li>Gather feedback to ensure we're on track </li></ul></ul><ul><ul><li>BENEFIT: </li></ul></ul><ul><ul><li>Users find the information they need </li></ul></ul><ul><ul><li>without looking for the needle in a haystack. </li></ul></ul> – the Future Vision
  11. 12. Ensure Up-to-dateness and Technical Accuracy <ul><ul><li>Take an inventory of existing documentation and check its up-to-dateness </li></ul></ul><ul><ul><ul><li>Ongoing on wiki: Documentation/Project_DocOOo_Structure </li></ul></ul></ul><ul><ul><li>Ensure regular checks of documents </li></ul></ul><ul><ul><ul><li>We need owners, editors, reviewers, watchlists </li></ul></ul></ul><ul><ul><li>Move obsolete versions to an archive </li></ul></ul><ul><ul><ul><li>Create an archive for older releases </li></ul></ul></ul><ul><ul><li>Focus on the current release </li></ul></ul><ul><ul><li>BENEFIT </li></ul></ul><ul><ul><li>Users find information that's </li></ul></ul><ul><ul><li>technically accurate and not outdated. </li></ul></ul> – the Future Vision
  12. 13. Allow Easy Contribution <ul><ul><li>Use the wiki as the main resource for collecting documentation input </li></ul></ul><ul><ul><li>Open source Sun owned documentation to remove restrictions on content use </li></ul></ul><ul><ul><li>BENEFIT </li></ul></ul><ul><ul><li>Users are able to contribute to the </li></ul></ul><ul><ul><li>documentation without needing to use </li></ul></ul><ul><ul><li>customized software or processes. </li></ul></ul> – the Future Vision
  13. 14. Minimize Duplication of Efforts <ul><ul><li>The customer is the user ! </li></ul></ul><ul><ul><li>Cooperate with ooauthors to distribute documentation pieces in a meaningful way and be a publication channel for ooauthors content </li></ul></ul><ul><ul><li>Cooperate with native language communities for localization of English content and reuse of existing non-English content </li></ul></ul><ul><ul><li>Work with the user forum and blogging community to harvest content </li></ul></ul><ul><ul><li>BENEFIT </li></ul></ul><ul><ul><li>A greater pool of documentation </li></ul></ul><ul><ul><li>for users, better management of </li></ul></ul><ul><ul><li>valuable writer resources. </li></ul></ul> – the Future Vision
  14. 15. Implement Transparent Processes <ul><ul><li>Develop distinct basic guidelines for collaboration </li></ul></ul><ul><ul><li>Maintain a roadmap and dashboard at a visible place </li></ul></ul><ul><ul><li>Make it easy to find places that need help </li></ul></ul><ul><ul><li>Make it easy to find out how to help </li></ul></ul><ul><ul><li>BENEFIT </li></ul></ul><ul><ul><li>Contributors can start contributing </li></ul></ul><ul><ul><li>quickly if the framework is clear and clean. </li></ul></ul> – the Future Vision
  15. 16. Include all Locales <ul><ul><li>Develop a documentation strategy that includes non-English locales </li></ul></ul><ul><ul><li>Implement localization processes that make it easy to go from one language to another </li></ul></ul><ul><ul><li>BENEFIT </li></ul></ul><ul><ul><li>Take advantage of the enormous </li></ul></ul><ul><ul><li>productivity of non-English authors. </li></ul></ul> – the Future Vision
  16. 17. Wiki Showcase <ul><li>Fresh Content on the Wiki: </li></ul><ul><ul><li>Developer's Guide, > 1,200 pages freshly open sourced from Sun sources </li></ul></ul><ul><ul><li>Admin Guide, 200 pages freshly open sourced from Sun sources </li></ul></ul><ul><li>Things to come: </li></ul><ul><ul><li>Application Help: contribute through the wiki! </li></ul></ul><ul><ul><li>BASIC Guide </li></ul></ul> – the Future Vision
  17. 18. Next Steps – Help Needed! <ul><ul><li>Doc and wiki layout proposals (Documentation Portal) </li></ul></ul><ul><ul><ul><li>restructure wiki after engine update </li></ul></ul></ul><ul><ul><ul><li>relaunch web site after cleanup </li></ul></ul></ul><ul><ul><li>Process flow for docs </li></ul></ul><ul><ul><ul><li>Implement a wishlist </li></ul></ul></ul><ul><ul><ul><li>Implement a dashboard </li></ul></ul></ul><ul><ul><ul><li>Implement an editorial and owner matrix </li></ul></ul></ul><ul><ul><li>Gaps </li></ul></ul><ul><ul><ul><li>Identify documentation gaps </li></ul></ul></ul><ul><ul><ul><li>and fill them :-) </li></ul></ul></ul><ul><ul><li>Audiences </li></ul></ul><ul><ul><ul><li>Identify target audiences </li></ul></ul></ul> – the Future Vision
  18. 19. Challenges, Issues, Big Rocks <ul><ul><li>Licensing, Legal, JCA </li></ul></ul><ul><ul><ul><li>Legal is a necessary evil </li></ul></ul></ul><ul><ul><ul><li>We must be in a clean legal environment to make it safe for everyone . </li></ul></ul></ul><ul><ul><ul><li>Ideally, every contributor files a JCA </li></ul></ul></ul><ul><ul><li>Wiki structure </li></ul></ul><ul><ul><ul><li>Wiki was primarily used by development engineering </li></ul></ul></ul><ul><ul><ul><li>As the wiki gets bigger and more important, we need a better structure and some rules (not many) </li></ul></ul></ul><ul><ul><li>Non-English content </li></ul></ul><ul><ul><ul><li>Combining English and non-English doc content will be major challenge for doc.oo.o and esp for localizers. </li></ul></ul></ul><ul><ul><li>Editorial process </li></ul></ul> – the Future Vision
  19. 20. <ul><li>Gerry Roderick Singleton Documentation Co-Lead † 12th May 2007 </li></ul><ul><li>Thank you, Gerry. You will be missed! </li></ul>