lca2011 – Wed Session 6 – Open Source Documentation

Open source Documentation –  Lana Brindley

  • User Interface + documentation = can get into program
  • People don’t think where manuals come from
  • Like a black box
  • At Redhat use 5 phase waterfall model
  • Phase 1 – Information plan – work out dates, audience, sources
  • Tools – wiki and ticketing system
  • Phase 2 – Decide what goes in – look like, title, abstract, where info, ID Subject matter expert. Google, wikipedia
  • Tools – wiki , bug system , master tracker bug
  • Phase 3 – create 1st draft of document – reviewed by legal, writers, technical review
  • bugs raise against doc, fixed, Quantity Engineering
  • Tools – publican, draft to svn,
  • Phase 4 – translation and publication
  • Up to 26 languages
  • Don’t publish dead-tree books, single page html, pdf, paged html, epub
  • Phase 5 – Review on process
  • Geographically spread out, , phone meetings
  • Advice:
  • Keep *some* documentation, blogs, wikis, comment code, that tech writers can use
  • Get organised
  • Choose your voice
  • Say what you mean
  • Use Short sentences. 15-20 words on paper, 10-15 on a screen
  • You’re not at University – there is not an exact word limit
  • edit with knife
  • each editing pass should make your document 20% shorter
  • read what you write, walk away from it so you read what it says not what you think it says. Read it aloud. Read it backwards (v short docs), or each sentence backwards.
Share