Documentation conference call #2

Hi, :slight_smile:

I'd like to propose another conference call.

IMHO, it would be a good idea to discuss and agree upon the best
medium for producing documentation, especially given the large amount
of documentation we need to produce, and the small number of
documentation team contributors that there are. I've put that item an
the agenda. Please do add any other items you'd like to discuss...

I have set up a poll to choose a time and date, and hope that we will
manage to assemble more people than last time. The information on the
confcalls page should be clearer, but please let me know if you need
any help.

The poll is at: http://www.doodle.com/qq8hiysi36fhkwy4

The confcall page is at:
http://wiki.documentfoundation.org/Documentation/ConfCalls#Conference_Call_Dates_and_Times

P.S. I'll be completing the write-up of the previous call over the
next day or so...

David Nelson

Hi, :slight_smile:

Hi, :slight_smile:

I'd like to propose another conference call.

IMHO, it would be a good idea to discuss and agree upon the best
medium for producing documentation, especially given the large amount
of documentation we need to produce, and the small number of
documentation team contributors that there are. I've put that item an
the agenda. Please do add any other items you'd like to discuss...

I have set up a poll to choose a time and date, and hope that we will
manage to assemble more people than last time. The information on the
confcalls page should be clearer, but please let me know if you need
any help.

The poll is at: http://www.doodle.com/qq8hiysi36fhkwy4

The confcall page is at:
http://wiki.documentfoundation.org/Documentation/ConfCalls#Conference_Call_Dates_and_Times

Ping. :smiley:

Does anyone feel like talking documentation and getting things a
little more organized? Or is this a cat-herding exercise? :wink:

David Nelson

IMO further work on the standards through the mailing list and wiki
will be more productive than another conf call at this time.

I guess we are not ready for a discussion that can really settle this issue.

First of all, we have not compiled the available options.
Only then can we have a discussion (to argue for or against any of those options).
Also, a two-hour discussion is not going to completely settle the debate (we will need many such sessions).
And besides the discussion won't succeed with just 3-4 participants (and the results won't be acceptable to the authors).

Instead, I recommend that Michael should set up a GraphMind (http://drupal.org/project/graphmind) on his Drupal site, and then we can create the mindmap for this subject.

The graph should address the following:
1. What are the basic requirements
2. Which tools are available (Drupal, mediawiki, Joomla, odt)
3. Which tools facilitate online collaborative authoring
   (This includes editing, comments, diff function that compares ANY two versions, acceptance/rejection of changes, rollback)
4. Which tools allow conversion to offline manuals that can be read on screen.
5. Which tools allow conversion to printable books with excellent formatting.

Once these choices and their relative strengths and weaknesses are known, we can then allow voting.

BTW I think not many people are even aware of Michael's Australian website. We should put a link to it from LibO's "Contribute" page.
Then more people will visit and see what's going on.

The Drupal site is still under heavy development and not ready for
publishing yet. We are deliberately avoiding publishing the Drupal
site prematurely to avoid misunderstandings as you have seen on this
list recently.

BTW: the site is the Official LibreOffice Drupal development site,
rather than the 'Australian' site. It is only there as we don't
currently have access to the libreoffice.org server.

Michael Wheatland

@ not "Australian" but "official" site
Yes, indeed. Probably we can just call it the "beta" site, to distinguish it from the "temporary" website.

BTW my main point was about having a brainstorming to select the documentation tool.
How do you (all) feel about that?

Take the case of the recent thread about using Pootle.
Different people are bound to have their own favorite tools.
Some people are attached to them emotionally.

A mind map will allow them to do advocacy for their favorite tool.
But it will also filter out all emotions, and allow us to focus on merits and demerits of each tool.

Instead of a mind map, we can also have a simple "tool-comparison table" like wikipedia.

Mind map allows us to plot any number of dimensions, though.

What do you think?

-Narayan

The status quo is that we use the wiki for coordinating and info
gathering and the mailing lists are there for discussion. Personally I
think these tools are pretty good until we develop a better solution.

We can create a 'requirements and tasks' list there for all of the
things that the documentation team is going to be involved in, however
I would suggest leaving the tooling up to the website team. As long as
all of the requirements for each task is met then we will be happy. If
people do have an attachment to a single tool then that is a
discussion for the people with that experience who will also be
developing the tool.

Mike Wheatland

We can create a 'requirements and tasks' list there for all of the
things that the documentation team is going to be involved in, however
I would suggest leaving the tooling up to the website team.

And I thought I WAS already a part of that web team (??)
OK how many goats I have to sacrifice to become a bona fide member? :wink:

Just listing the requirements means identifying the problem statement.
That alone is not enough, because it won't identify the documentation tools that satisfy those requirements.

Further, all authors would have to agree on common set of tools so that they can collaborate.
(Each author can not insist on using his own tool; otherwise there will be compatibility issues later.)

The choice of authoring tool should not be finalized based on the preference of a few early joiners.
It should be based on a thorough analysis and comparison of the available tools.

Since that conference call didn't materialize to finalize the authoring tool, then the next option is the website.

In fact, if Drupal itself has a powerful books module which can be export as viewable OR printable pdf.
Thus "website" and "documentation" are not isolated concepts.
In fact, regardless of the authoring tool chosen, the LibO website will execute the workflow partly or fully.
So the web team is very much a facilitator/enabler for the documentation team.
Therefore the web team and the documentation team would have to work together.

If people do have an attachment to a single tool then that is a
discussion for the people with that experience who will also be
developing the tool.

I don't know what you mean, but no one is going to develop any tool, right?
The authors will simply make use of an existing offline/online application or service.
Say, one of the options is for you to install the Drupal book module.

-Narayan

Narayan Aras wrote:

Further, all authors would have to agree on common set of tools so
that they can collaborate.
(Each author can not insist on using his own tool; otherwise there
will be compatibility issues later.)

Not necessarily. Localization teams at OpenOffice.org, for example, use
different formats (some use .po files, others use other formats) and
within the same team use different tools (for example, the Italian team
uses .po files, but some translators prefer to work online with Pootle,
some offline using poedit, and some offline using OmegaT). Then
everything is converted to yet another format (.sdf) for inclusion in
the OpenOffice.org sources - and the same is currently happening for
LibreOffice.

Since all are volunteers, any forced standardization is a risk. So the
points raised by Sophie are important: there will be people willing to
help only if they can do it "the usual way".

Regards,
  Andrea.

I think you misunderstood my point: The actual tool used by any individual has to be compatible with the others; otherwise there won't be effective collaboration.

One tool cannot serve all purposes. So it has to be a set of tools.
But those tools have to be mutually compatible.

When OOo authoring started, many of the collaborative authoring tools were not so sophisticated.

OOo authors may be having their legacy issues. But if we copy those old decisions and habits here, we would be losing the substantial advantages offered by new tools.

So now is our chance to re-examine the whole case again, and escape being a victim of the past.

-Narayan

Hi Narayan and all, :slight_smile:

1) This thread is about organizing a documentation conference call, so
could you please start a new thread for discussion of other subjects?
Thanks if so. :wink:

2) Discussion of the subject of what tools the documentation team
should use has revealed that there are several different viewpoints,
ranging from using the TDF wiki, to "working at home" with ODT files,
or developing a workflow on Drupal, or using the oooauthors site along
with ODT files. Even a Drupal-based workflow could involve several
quite different options. Plus, the choice of a Drupal workflow is
dependent on TDF first officially adopting Drupal as a tool, and I am
told that this can't happen until the board of directors has been
appointed.

This is precisely why I want to organize another documentation
conference call: to discuss the subject of a workflow ad tools for
documentation production.

There is currently a poll online to choose a time and a date, but
given the low response, I may have to set up another. I, myself, am
busy with other LibO-related work this weekend, but I could manage
Sunday or Monday.

Again I would invite you all to take part.

The poll is at: http://www.doodle.com/qq8hiysi36fhkwy4

The confcall page is at:
http://wiki.documentfoundation.org/Documentation/ConfCalls#Conference_Call_Dates_and_Times

David Nelson

Hi, :slight_smile:

I have extended the poll to include dates up to Monday, December 20,
2010... If you already entered dates and times, please review and
enter other later availabilities, if possible.

If you didn't already, could you please consider doing so?

TIA if so. :wink:

P.S. If you want to post about topics off-topic to the conference
call, please start another thread, huh? They are free and cost
nothing! :wink:

David Nelson

Hi,

Hi, :slight_smile:

I have extended the poll to include dates up to Monday, December 20,
2010... If you already entered dates and times, please review and
enter other later availabilities, if possible.

I've entered the dates/times, when I'm available (at least in theory).
In practise it could be, that I can't attend, because my connection
decides that it doesn't want to work. :frowning:

Sigrid