Documentation/ConfCalls/Minutes-2010-11-28

Minutes of the Documentation Call Conference of November 28, 2010

Introduction

This documentation team conference call was organized and hosted by David Nelson. The number of participants was lower than David hoped for: 5 active speakers, which highlights the need for a major recruiting campaign (see further on for more about that).

There was also a small number of listeners. All in all, the discussion lasted some two and a quarter hours.

Agenda

The agenda was as follows:

1. Self-introductions by current and prospective team members;
2. Current situation regarding documentation work;
3. Usage of OOoAuthors website for tracking docs;
4. Timing of public availability of draft user documentation;
5. Decision-taking about when a chapter or a book is ready for publication;
6. Formats to provide user guides in;
7. Format for source for user guides;
8. Offer from Friends of OpenDocument Inc. concerning printed manuals;
9. Other user-oriented materials to provide;
10. Documentation team responsibility for updates to help files;
11. Documentation team responsibility for documentation aimed at programmers, sysadmins, etc;
12. Documentation-related bugs from the bug tracker assigned to David Nelson;
13. Information about the proposed Drupal website as regards documentation work;
14. Information about WikiHelp;
15. Review and adoption of new look/feel of user guides with Liberation Sans font.

Write-Up of the Proceedings

Self-introductions by current and prospective team members.

The people taking an active part in the discussions all presented themselves briefly.

Among the active participants were:

• David Nelson (conference moderator, a technical documentation professional with a couple of dozen years experience, and a recently-joined contributor to the documentation project);
• Jean Hollis Weber (a long-time documentation contributor, and a documentation team co-lead within OpenOffice.org for the past couple of years; she operates the oooauthors.org site contributing documentation to the OOo project);
• Michael Wheatland (a new contributor to LibreOffice, heavily involved in the planned Drupal-based website, and now getting involved in the SilverStripe site);
• Andreas Mantke (a contributor to OOo since 2002 and now a member of the LibreOffice community; developer of the oooffice Plone site).
• Jan Holesovsky (Kendy, a former OOo developer and now one of the LibreOffice developers, currently working on the WikiHelp project);
• Ron Faile was listening-in to the call but only contributing via the IRC chat. Ron is an active writer of documentation, and is now contributing work to the LibreOffice project.

Current situation regarding documentation work.

David explained that he had wanted to organize the conference because he saw work on documentation as being almost at a standstill, with no identifiable team at this time. He'd like to get things moving, and would like to identify someone to be at least an acting team leader until such time as the SC appoints or holds a vote for a team lead.

He asked Jean Weber whether she would like to take up that role at least on a provisional basis. Jean explained that she's been doing user guides for OOo for about 8 years, and was voted co-lead for OOo documentation a couple of years ago.

At the moment, that's where she wants to stay, but she's interested in helping make the oooauthors.org site useful to the LibreOffice project if LibO contributors would like to use it. She's not really into all the things around a startup project, is retired, and has a busy life. "But who knows? Maybe next year?" she said.

Michael asked her what skills would be required for a new documentation lead for LibreOffice. Jean replied that having time and being available a lot, particularly in the beginning. Some experience of coordinating a group of people would probably be pretty useful, she added, but a coordinator mostly needs experience in planning and coordinating. Encouragement and nagging would be useful abilities.

David asked if the documentation effort at OOo was active. Jean says they have been doing some work, but do lack manpower. There are days when she feels like she's most of the team, and seems to be doing most of the work by far. They've just finished updating the Getting Started Guide for 3.3 (Ron has been active in this). They don't have enough people actually copy-writing. They have about half a dozen people contributing to some extent over the past few months.

Jean feels that people are needed to do mentoring. There's a shortage of people who really know how to write, and it might be good to try and train people into the role - although it would involve a lot of work.

Ron Faile has finished converting the documents for the Getting Started Guide. (And has pretty much finished converting the Writer Guide.)

David pointed out that the UI of OOo and LibO is going to start diverging in 3.5 or maybe 3.4, and that this is an important consideration for a documentation writer, and asked Jean what her thoughts were on that. Jean said that probably in a year or so the UIs will have diverged to such a point that starting with the same set of guides might not work. Jean says that in OOo 3.3 there are some changes in the Impress UI, but no great changes overall.

Usage of OOoAuthors website for tracking docs

Should we use the OOoAuthors website for tracking docs during writing/reviewing/editing, at least until the proposed Drupal site is ready? If not, what/how/where should we track doc development?

Micheal says that he thinks that, at the present time, until there's a major divergence, it's a better approach to work on the existing documentation for OOo, collaborating with Jean via the oooauthors.org site. He feels that the quality of OOo documentation is high and that we should use it until such time as we work up a system of our own over the next few months.

David explained that he feels committed especially to the LibreOffice project, but is willing and keen to learn from Jean's experience and is willing to produce documentation in conjunction with oooauthors.org as long as he doesn't have to convert stuff to OOo. He basically prefers to put all his available time into LibO.

David asked about developer documentation at OOo. Jean says it's the Oracle guys and a number of volunteers working in cooperation with them that deal with dev docs, and that they principally use their wiki.

Kendy says that there is quite extensive documentation on how to write extensions, but it is not that useful for core development of LibreOffice. There has not been much commenting written into the OOo code base, so it's not possible to generate much documentation from that for LibO. They have a certain amount of material on the wiki how to build LibO, how to get involved in development, but there's no real description of the inside working of LibO. The OOo extensions documentation could be ported. Kendy pointed out that the LibO devs foresee incorporating a number of worthwhile extensions directly into LibO.

If printed books are desirable, should we accept the offer from Friends of OpenDocument Inc (an Australia-based not-for-profit association), with profits from book sales going to the TDF?

Friends of OpenDocument, Inc (FoOD for short), an Australia-based not-for-profit association, has offered to produce printed copies of the user guides for LibreOffice.

• Sales are currently through Lulu and books can be made available through Amazon and other online retailers through the FoOD account at Lightning Source (an on-demand printer owned by Ingram, the largest distributor of books through online and offline bookstores).
• There is no cost for making books available for sale on the Lulu website. However, there are costs for making books availalbe through Lightning Source to Amazon etc.
• Books are given Australian ISBN through the FoOD account.
• FoOD takes 50cents per book sold to cover admin costs, mostly for accounting/auditing and filing of paperwork required by the government. FoOD does not need to pay taxes on sales, either in the USA or in Australia.
• We provide full accounting: summaries on the FoOD website, details available on request.
• All profits from sales of LibO books would be forwarded to the TDF account. We can work out details of how often to do this.
• FoOD would like someone from the LibO documentation team to take responsibility for providing cover art and interior PDFs suitable for use with Lulu. Full information and training will be provided.

TDF is, of course, welcome to set up its own account at Lulu or Lightning Source or elsewhere, instead of using FoOD's services.