User Docs & Other Support Services

This part is a place to collect some discussion about the relationship between user documentation and other user support services. Please add your comments below, and please send them to the ooo-dev list as well.

Rob Weir wrote on the ooo-dev list:

I'd urge you to think boldly about what we could do. I know we don't have the resources currently to do much more, but the truth is we don't get the resources until we articulate a vision about what we could do. If we have a compelling vision, then we can try to entice volunteers, corporate sponsors of editors, etc.

So if resources were not an issue, what would we do? What could we do? How could a fully resourced doc effort best contribute to the overall success of the project and our users?

And in a follow-up note:

My general view is this: After 10 years of OpenOffice.org we have about as many volunteers as the status quo will ever get us. If
someone is really interested and able to contribute to the project, they either are doing so already, do doing so for LibreOffice. This is due to the great work OOo did over the years raising awareness of the project.

The move to Apache changes things somewhat. The project is now a community-led project, not a corporate-led project. It now has a
permissive license. This changes the equation and could bring in some new contributors. I think this will mainly be new
corporate-sponsored contributors. Not exclusively, but the changes that the move to Apache will bring will be particularly attractive to such contributors.

If we want to do better than that, then we need to do more then the status quo. We cannot just do the same things and expect better results. We need to do more than just migrate/translate/rehost/move OOo to Apache. We need to up our game. This requires more volunteers, of course. But the magic is, by expressing a bolder vision we can attract the kinds of volunteers that can make this happen.

Ask yourself, if you were not already involved, and had a history with the project, what would interest a person of your skills in
volunteering? That's the kind of person we want to attract!

I'm not a documentation expert, but I've noticed some trends:

1. Moves to using structured formats that allow content to be more easily sliced and diced and targeted to different outputs. DITA is one way of doing it, but similar approaches could be based on ODF.
2. Collaboration with users. Several companies do this their online doc. Each page allows comments, a thread at the bottom of the page for user's to enter additional observations, tips, corrections, etc.
3. Multi-media. It is amazing what a 30 second video clip can teach you about pivot tables that would take pages of text to explain.
4. Tightening the bounds between documentation, product help, support and training. That goes back a to 1) above, the structuring of the information to make it reusable.

Would things like the above attract more interest?

To which Jean Hollis Weber responded, in part:

I agree with your points above....

Whether overtly working towards those goals would attract more interest from appropriately-skilled people, I can't guess. Certainly
(3) would attract people who aren't motivated toward print media. We've had intermittent interest at OOo over the past few years, but nothing's ever come of it. I think it was mainly from people who wanted to do multimedia but didn't really know much about it, and there was no one to act as a mentor to the others.

.....

I've been looking at the Symphony documentation wiki 1 and am impressed with it as a good example of one important type (subset) of user documentation: what I would call well-organised and searchable how-to's. I particularly like the way there is a set of original non-editable docs and a set of editable docs derived 1-to-1 from the original docs, each set with clear links to the other. 2 is an example. As mentioned in your point (2), the pages offer an opportunity for readers' comments as well as direct editing. This overall approach seems to me to meet the requirements of both camps regarding end-user docs: controlled "official" docs, plus an immediate opportunity for community participation. (I haven't looked around enough to see how someone might offer a new page of info, not just respond to existing pages, but I'm sure it's there.)

1 http://www-10.lotus.com/ldd/lswiki.nsf/xpViewCategories.xsp?lookupName=Lotus%20Symphony%203%20Documentation
2 http://www-10.lotus.com/ldd/lswiki.nsf/dx/Inserting_an_Entire_Text_Document_ls3

Jean then wrote to the ODFAuthors list, asking "what would you like to see as documentation/user support for AOOo?"

Nino Novak responded (copied here with permission):

Here is a first rough collection of requirements/ideas/wishes which may need being discussed/prioritized/concretized a bit

• a centralized integrated documentation place for all flavours + forks of the OOo/LibO family
• very good searchability (I doubt Google is sufficient?)
• sync'ed multilanguage documentation (e.g. like php or mysql docs)
• immediate availability of any document in any of the main delivery formats (HTML, PDF, ODT) - best generated "on the fly" or regenerated on any change from a master
• support for "filtered views" (showing only the documentation for a given combination of software flavour/fork + Version + Language)
• support for a reviewing workflow similar to ODFAuthors or Alfresco
• support for translation workflow with fallback to original language (or English or whatever)
• support for translations in any direction (not only from en-> other)
• arbitrary diff support (not only between two history versions of a page like in the wiki but between any two pages/documents)
• nice2have: integration of translation memory with GUI l10n
• nice2have: interlinks with application help
• end user commentable pages
• easy community involvment (with a well thought or configurable rights hierarchy for e.g. typo correctors, editors, reviewers, document publishers etc.)
• licence agreement on any edit or on account creation (or both?)
• mail notification on page change with author + comment (best with optionally included diff)
• votable pages to see what is considered high/low quality
• good statistics to see
  • what infos are searched most
  • what search terms are used
  • what is missing most
• enhanced credits page (who - what - changed word counts, how many etc.)