FirefoxSummit/2006/WhitherHelpDocumentation

Session Title

Whither Help Documentation? The current state of (Firefox, although this applies elsewhere too) help documentation and discussion of possible ways to improve it and the process

Session Leader

Jeff Walden

Summary

Help docs were originally a nice-to-have for Firefox; they only appeared because a small group of people made the effort to see them happen. Localizers weren't even required to localize help for Firefox 1.0. Over time this has changed, and 1.5 and 2.0 both included help as a required part of a localization (although the locale is free to write its own if it wishes).

However, help is still a world unto itself. Help documentation is not subject to l10n freezes, be they slushy or not, generally up until some ill-defined "last minute". Firefox 2 beta 1 was released with completely broken Help in ~20 locales (the un-updatedness of Help was used as an excuse to actually make releases for the affected languages). The final help changes for en-US occurred late enough that localizers couldn't fix them for Firefox 2 RC1, and they only were able to make those changes because an RC2 had to be made.

Clearly, the current way of doing things doesn't work. Is it fixable without major changes? Perhaps (recall that perfect is the enemy of good). Do we need more people writing help? Yes (at least until I finish college ;-) ). What can be done to solve these problems? We'll be brainstorming solutions to these problems at this session.

Agenda

(This is to some degree a brain-dump; I hope to solidify exact details by Tuesday morning, i.e. before I fly out. Suggestions for additions, changes, improvements, etc. are welcome.)

• a short history of the Firefox Help project internally
• review of help docs effort for Firefox pre-1.0, 1.0, 1.5, 2.0 (with varying degrees of seriousness for the term "effort")
• current (and growing) problems
  • too few consistent contributors (not just our problem)
  • time constraints for those who are involved (a.k.a., Real Life)
  • technical barriers to involvement
  •  ???
• discussion of possible solutions
  • moving the docs online
    • things which would need to happen to make it work
    • advantages
    • potential problems
      • l10n?
      • platform-specificity
      • doesn't really help the "too few people" problem
  •  ???
• get the ball rolling (I really don't want this to be a dead-end discussion which doesn't have followup action)

Interested Attendees

Please add your name here if you're likely to attend this session, this will help prioritize sessions and minimize conflicts

• Jeff Walden
• Nick Thomas
• Zach Lipton
• Ian Hayward
• Axel Hecht
• Majken Connor