General questions and suggestions

Hi Nino, :slight_smile:

General question: since it's a wiki, doesn't it make more sense to
have the docs in wiki format rather than ODT?

Which do you personally prefer?

I don't have a preference, except that it's probably technically
easier to write in ODT and then be able to export to the wiki, PDF and
any other formats the project chooses to publish in. I guess that in
the absence of any recommendations from a documentation project lead,
I'd just watch contributors' habits and see from there.

Historcally, the question has been raised a couple of years ago in the
ooo project. The answer was to use the format in which most people
preferred to contribute (which seems pretty rational). Both
possibilities were offered, but AFAIK the community has preferred ODT
for writing User Guides by far, whereas Dev Documentation has been
mainly produced in wiki form.

I don't think that a formal decision has been made. Up to now, there is
no official (or inofficial) team in charge of the doc project. So who
should make a decision? Things are just evolving :wink:

Jean Hollis Weber seems to be active in documentation, and seems to
have been an old-timer in the OOo project (if I'm not mistaken)...
Maybe he's the kind-of de facto lead for the moment?

But anyways - I think it would be a good decision to take ODT as master
format for User Guides and Wiki as master for Developer documents.
Conversion ODT -> Wiki and vice versa is possible but time consuming,
so keeping both formats in sync does not seem a good option unless we
have enough people taking the task.

With using drupal as CMS there could be a third option: to produce
drupal master documents which then could be offered in web form and
then transformed to ODT/PDF, but this possibility has to be implemented
and tested still. This will take some months, I think.

Nevertheless, for quick drafting, the wiki can always be used without
problems.

OK, thanks, that gives one an idea. :slight_smile:

I plan to work through the posted material and do some proofreading.

Fine.

OK, then I'll continue from where I started then. Thanks for the pointers. :slight_smile:

David Nelson

Hello David,

> Historcally, the question has been raised a couple of years ago in
> the ooo project. The answer was to use the format in which most
> people preferred to contribute (which seems pretty rational). Both
> possibilities were offered, but AFAIK the community has preferred
> ODT for writing User Guides by far, whereas Dev Documentation has
> been mainly produced in wiki form.
>
> I don't think that a formal decision has been made. Up to now,
> there is no official (or inofficial) team in charge of the doc
> project. So who should make a decision? Things are just evolving
> :wink:

Jean Hollis Weber seems to be active in documentation, and seems to
have been an old-timer in the OOo project (if I'm not mistaken)...
Maybe he's the kind-of de facto lead for the moment?

As the ooo community as a whole did not follow the transition to LibO,
my feeling is that the community here is kind of starting from scratch.
We should take the chance and try to establish our own identity, leads
and processes. IMHO, of course.

But maybe I'm wrong, so don't take my words for the only truth possible.

Jean, you're always welcome to take/continue your role as doc lead here,
too :slight_smile:

Nino

Hi Nino, :slight_smile:

But maybe I'm wrong, so don't take my words for the only truth possible.

Sure, I understand, and thanks again for the helpful info. :slight_smile:

David Nelson

To me, it seems easier to compile the documentation in web form first, then
export it to ODF or PDFs. Only one person can work on a document at a time,
and I would imagine most people would want to view the documentation online
before downloading a text document.

David,
Sorry, it was an attempt at a witty retort containing as many words spelled
differently in the American dialect.
I had a bit of trouble fitting 20+ words in three sentences which would be
considered to be incorrectly spelled by an American.

Honestly I have no opinion about this at all. I am more than happy to
contribute in ANY English dialect.
But it is a good point you raise. Thanks for kicking this discussion off.

Hi David

I am lurking the documentation mailist to help pick aspects of the documentation process that may apply to the development of the TDF/Drupal Drupal site. I'm a member of the Drupal team.

However, I am also a member of the marketing team. If I could perhaps just add my opinion to this.

From the perspective of the "outside world" the public face of the LibO documents section, it would seem to make sense that documents be provided in the first place in our native ODT formats. This should be trumpeted as our success in document achievement. I think that this is an expectation that we all share.

Also, if we are going to keep advertising the virtues of the ODF files. It would seem to make sense that we find ways to make the ODF files system "play nice" with the internal document flow. What better occasion would we get than having the use of a corporate-like structure such as the "TDF/LibreOffice document team division" use the ODF files internally at developing documents from start to end. We have our devs on-side for the development of an Office Suite championing the use of ODF, would it not make sense that we would try to make the creation/editing of internal ODF documents part of the internal process? The devs could could help in making this work. We could then, without any doubt, suggest and prove that using the ODF in creating documents in a corporate structure, from start to end production, is entirely and assuredly possible.

If so, as a group of committed document editing professionals, as you all are, you could use this occasion to streamline the ODF documents to work in such a process.

This would certainly help in marketing our LibO Suite as a viable office suite for the corporate/enterprise world.

Just my thoughts.

Marc
Member of the TDF/LibO Marketing Team
Member of the TDF/LibO Drupal Website Development Team

Thanks Frank for these links.

Marc

Marc,

you're certainly right but nevertheless I'd propose to stay pragmatic
and to leave it to people to write documents the way they like most and
to provide the infrastructure to transform documents (from ODT to web
or vice versa).

Nino

Hi Michael, :slight_smile:

David,
Sorry, it was an attempt at a witty retort containing as many words spelled
differently in the American dialect.
I had a bit of trouble fitting 20+ words in three sentences which would be
considered to be incorrectly spelled by an American.

Honestly I have no opinion about this at all. I am more than happy to
contribute in ANY English dialect.
But it is a good point you raise. Thanks for kicking this discussion off.

No problem :slight_smile: I regret that my burned-out intellect didn't rise to
the challenge. :smiley:

David Nelson

Hi Marc, :slight_smile:

Also, if we are going to keep advertising the virtues of the ODF files. It
would seem to make sense that we find ways to make the ODF files system
"play nice" with the internal document flow. What better occasion would we
get than having the use of a corporate-like structure such as the
"TDF/LibreOffice document team division" use the ODF files internally at
developing documents from start to end.

+1 ... And a better starting point for conversions to other formats,
too, IMHO, after I thought further about the question. :slight_smile:

David Nelson

Thanks Nino.

That is exactly what I am proposing. If we can't use the ODF in a pragmatic way with our suite, then, how can we advertise that it is so to others?

Marc

It's not only about being able to use ODF but in addition about what is
the most efficient/pragmatic workflow for delivering good quality
documentation in time. Therefore, we have to test all possibilities and
to choose what is most appropriate. And stay prepared to adapt/change
our workflow when needed.

Nino

Yes, I'm an old-timer in the OOo project, having been around since 2002,
lead editor at OOoAuthors since 2004-ish, Co-Lead of the Documentation
Project since early 2009 (continuing).

However, I am too busy to take on a lead role with LibO docs. I see my
role as "senior adviser" -- "senior" in terms of the OOo old-timer
aspect as well as my age. And BTW, I'm a she. :wink:

Regarding the "international English" vs "US English" discussion, at
OOoAuthors we had been using the US English version of the *software*
because way back when, the British English version was not readily
available as it is now. I suspect the US-Eng version is still more
commonly used internationally, but I've not attempted to find any
statistics on this.

So if the screenshots are from the US-Eng version of the software, then
the text should be in US-English *spelling* to match the software.
However, the *punctuation* can (and IMO should) be in the more logical
"British" style. Actually, the differences are minor and most of them
are easily avoided.

--Jean

Marc, you have expressed my opinion on this subject better than I can.
Thank you.

--Jean

Hello David,

> > Historcally, the question has been raised a couple of years ago in
> > the ooo project. The answer was to use the format in which most
> > people preferred to contribute (which seems pretty rational). Both
> > possibilities were offered, but AFAIK the community has preferred
> > ODT for writing User Guides by far, whereas Dev Documentation has
> > been mainly produced in wiki form.
> >
> > I don't think that a formal decision has been made. Up to now,
> > there is no official (or inofficial) team in charge of the doc
> > project. So who should make a decision? Things are just evolving
> > :wink:
>
> Jean Hollis Weber seems to be active in documentation, and seems to
> have been an old-timer in the OOo project (if I'm not mistaken)...
> Maybe he's the kind-of de facto lead for the moment?

Jean is a "She", and she has led the OOoAuthors project since it's inception
and if you had done a bit of research you would have found out that she is a
highly respected Technical Editor and a published Author on things OOo. And
I'm not so sure she would get off being referred to as an "OldTimer" :slight_smile:

Frankly I see no reason why we don't use OOoAuthors as the place to produce
documentation. The software in general will be the same with minor
differences. The challenge for the LibreO team will be keeping track of and
documenting those differences. OOoAuthors is not part of OOo it is an
independent group that happens to contribute to the OOo documentation project.
Any fork or version based on the OOo source could use the OOoAuthors Manuals.

As the ooo community as a whole did not follow the transition to LibO,
my feeling is that the community here is kind of starting from scratch.
We should take the chance and try to establish our own identity, leads
and processes. IMHO, of course.

To me, the most productive thing people could do is join the OOoAuthors team
and contribute there, then take the product and edit and add to suit for
LibreO. For instance pdf import is installed by default, a chapter for that
or standard extensions would have to be added and so on.

But maybe I'm wrong, so don't take my words for the only truth possible.

Jean, you're always welcome to take/continue your role as doc lead here,
too :slight_smile:

I'm so glad that you have the Authority to grant this. :confused:

cheers
GL

Just a suggestion, but why not have a British version of the user guides as well as a US version? That way each user can have it in his/her native language conventions.

As for the workflow, what about using the odf format for creating the user guides and posting the actual files online as soon as changes have been made and then, after they are finished, converting them to the wiki. Save as pdf is a simple process as well.

Ron

Just a suggestion, but why not have a British version of the user guides
as well as a US version? That way each user can have it in his/her
native language conventions.

If someone has the time to redo the books and those screenshots that
differ, that would be great. But at OOo we have enough trouble just
keeping one set of manuals up to date.

As for the workflow, what about using the odf format for creating the
user guides and posting the actual files online as soon as changes have
been made and then, after they are finished, converting them to the
wiki. Save as pdf is a simple process as well.

That is what we do at OOo, and as I've written here before, IMO that's
the best overall approach... especially since the people who do most of
the work on the user guides prefer to create/review/edit in ODT.

As I'm sure others have pointed out, the best workflow is one that
*works* in terms of getting docs done using the resources available.

--Jean

Thanks Nino.

Yes, always best to use the right tool for the job. I was just trying to comment that we were actually the people building the tool and it would be quite the opportunity here to better fine tune our tool in this process while the document team had a direct feed to the devs. What better way to prove that your tool if built for complete document production from start to finish.

But I understand that there are time and schedule constraints to meet.

Cheers

Marc

sorry, it's not about authority but opinion - so I'd better stated:

"I've no doubt that you're welcome here, too"

:wink:

Nino
speaking always in behalf of myself unless explicitly stated

Sorry to the documentation team if this seemed a negative comment on your production process. I think that most members who have taken the time to read your posts have come to the same conclusion as I, in that you are very professional in your approach to documentation as well as in respecting the production flow.

In some ways I feel apprehensive to thank you because I don't think that any of you would be anything else than this in any other comparable tasks. Thank you and my respects.

But in the same breath ... I will still add my opinions when and where I can. :slight_smile:

Marc