Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Evergreen Documentation Lightning Talk

5,571 views

Published on

A five-minute description of the forward path for documentation for Evergreen open source library software. (There is a much longer version of this talk that will also be uploaded.)

Published in: Technology
  • DOWNLOAD THE BOOK INTO AVAILABLE FORMAT (New Update) ......................................................................................................................... ......................................................................................................................... Download Full PDF EBOOK here { https://urlzs.com/UABbn } ......................................................................................................................... Download Full EPUB Ebook here { https://urlzs.com/UABbn } ......................................................................................................................... Download Full doc Ebook here { https://urlzs.com/UABbn } ......................................................................................................................... Download PDF EBOOK here { https://urlzs.com/UABbn } ......................................................................................................................... Download EPUB Ebook here { https://urlzs.com/UABbn } ......................................................................................................................... Download doc Ebook here { https://urlzs.com/UABbn } ......................................................................................................................... ......................................................................................................................... ................................................................................................................................... eBook is an electronic version of a traditional print book THE can be read by using a personal computer or by using an eBook reader. (An eBook reader can be a software application for use on a computer such as Microsoft's free Reader application, or a book-sized computer THE is used solely as a reading device such as Nuvomedia's Rocket eBook.) Users can purchase an eBook on diskette or CD, but the most popular method of getting an eBook is to purchase a downloadable file of the eBook (or other reading material) from a Web site (such as Barnes and Noble) to be read from the user's computer or reading device. Generally, an eBook can be downloaded in five minutes or less ......................................................................................................................... .............. Browse by Genre Available eBOOK .............................................................................................................................. Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, CookBOOK, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult, Crime, EBOOK, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, ......................................................................................................................... ......................................................................................................................... .....BEST SELLER FOR EBOOK RECOMMEND............................................................. ......................................................................................................................... Blowout: Corrupted Democracy, Rogue State Russia, and the Richest, Most Destructive Industry on Earth,-- The Ride of a Lifetime: Lessons Learned from 15 Years as CEO of the Walt Disney Company,-- Call Sign Chaos: Learning to Lead,-- StrengthsFinder 2.0,-- Stillness Is the Key,-- She Said: Breaking the Sexual Harassment Story THE Helped Ignite a Movement,-- Atomic Habits: An Easy & Proven Way to Build Good Habits & Break Bad Ones,-- Everything Is Figureoutable,-- What It Takes: Lessons in the Pursuit of Excellence,-- Rich Dad Poor Dad: What the Rich Teach Their Kids About Money THE the Poor and Middle Class Do Not!,-- The Total Money Makeover: Classic Edition: A Proven Plan for Financial Fitness,-- Shut Up and Listen!: Hard Business Truths THE Will Help You Succeed, ......................................................................................................................... .........................................................................................................................
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Follow the link, new dating source: ♥♥♥ http://bit.ly/2F4cEJi ♥♥♥
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Dating direct: ❶❶❶ http://bit.ly/2F4cEJi ❶❶❶
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Oh and thanks to berbercarpet on Flickr for that ugly-animal picture!
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here

Evergreen Documentation Lightning Talk

  1. 1. The Problem, Some People, A Plan, and a Pickaxe: A Report-Out from the May 20, 2009 Documentation Discussion Evergreen International Conference 2009 Karen G. Schneider, Equinox Software & Paul Weiss, Sage Library System
  2. 2. The Problem…
  3. 3. Evergreen documentation (Current) • Some technical documentation generated during development processes • Some legacy materials from PINES roll-out • An increasing quantity of community- generated end-user documentation ▫ Often duplicating/overlapping existing efforts and located here, there, everywhere
  4. 4. Core docs problems • Not integrated into development or tied into releases • Fuzziness between “core” and “community” docs • No clear, community-chosen toolset • Lack of committed resources • No intentional production process • No identified leadership
  5. 5. We’re an open source STEREOTYPE!!!!
  6. 6. Current Formats: The 3 Ws • Wiki — the Dokuwiki instance • Word — word processing documents • Whatever — PDF, text, random formats for movies, audio, etc.
  7. 7. With every additional format, another kitten dies.
  8. 8. And not the best of first impressions!
  9. 9. Other unintended consequences… • Software knowledge locked in developers’ brain trust • Much time wasted asking basic questions • Much time wasted answering basic questions • No unified, well-organized, “one voice” presence
  10. 10. Previous EG documentation activities • Mailing list (ongoing) • Training sessions (early on) • A proposal (Sep 07) • Another proposal (Jan 09) • Conifer intern (Jan – Apr 09) • A response (May 09)
  11. 11. Resources and Opportunities • Growing perception of need • Critical mass • Good communication tools • Areas of in-house expertise • Wide assistance/input from other FOSS projects
  12. 12. The People…
  13. 13. Meet the DIGGERS! (Documentation Implementation Group) • Approx. 20 people met 5/20/09 • Committed to building a docs project • Will meet every other week • Karen Schneider and Paul Weiss, project coordinators
  14. 14. The Plan…
  15. 15. DIGGER Recommendations • A single-source, open, standards-based format for core Evergreen documentation • DocBook XML as the core authoring format • Any format (Word, Wiki, Whatever) for initial documentation contributions
  16. 16. Can you DIG it? There’s a role, big or small, for everyone… • Documentation production (writing, editing, design, testing, CSS design, infrastructure help, etc.) • Documentation project planning • Documentation project management
  17. 17. The Pickaxe…
  18. 18. Toolset “highly desirables” • Cross-platform • Single-source, reusable content • Support for distributed, modular authoring • Facilitates translation • Standards-based • Well-established user community • Widely available fee-or-free publishing tools
  19. 19. Single-Source Publishing: One Spirit, Many Gifts • Same source produces print, PDF, HTML, help files • Can tie source to versions • Lends itself to translations • Central control for look/feel/style • Good for distributed labor efforts
  20. 20. DocBook • OASIS standard • XML schema (As of 5.0, RelaxNG, not DTDs) • Friendly, responsive user community • Designed for technical documentation • Some “Evergreen expertise” with it • Good mix of “fee or free” tools available
  21. 21. Significant OSS DocBook Implementations • Linux • Fedora • PostgreSQL • PHP • TortoiseSVN • Subversion • FreeBSD • Gnome
  22. 22. Getting to HTML Most writers will only see and work with these files. DocBook XML File* XSLT HTML Files Processor DocBook Stylesheet *May also include CSS and a Makefile
  23. 23. Common DocBook Toolset • DocBook-aware XML editors— XMLMind, Eclipse (free); oXygen, $ • XSL stylesheets (free, nice selection of default sheets on docbook.org) • XSL and FO processors — free ones are good — see xsltproc, Saxon, FOP • Web design tools — for creating CSS • Repository — for check-in, version control, release tagging, project oversight • Website – capable of supporting desired functionality
  24. 24. Possible DocBook Workflow • Documentation is written in or converted to DocBook XML • Writers “check in” their work to a repository • Editors review and edit XML so it is valid and well- formed • Designers create CSS • Editors select XSL stylesheets • Editors transform XML to HTML or other formats with an XSL processor • Editors upload HTML (and any associated images) to a website
  25. 25. Essential DocBook Resources • Web: Docbook.org • Email list: Docbook-apps • Book: Norman Walsh, DocBook: The Definitive Guide • Book: Robert Stayton, DocBook XSL, 4th Edition
  26. 26. DIGGER Group Commitments • Single-source documentation • DocBook format • Accept content “by any means necessary”
  27. 27. DIGGER Startup Activities • Promote the existence of DIGGERS • Carve out roles • Develop process plan • Create style guide • Address IP issues • Build a DocBook “proof of concept” page linking out to community documentation • Provide samples, checklists, and heavily-annotated templates
  28. 28. Think of the kittens. Help the DIGGER Project!

×