General questions and suggestions

Hi, :slight_smile:

General suggestion: would it be a good idea to specify somewhere that,
when drafting documentation in English that US spelling is the norm?

General question: since it's a wiki, doesn't it make more sense to
have the docs in wiki format rather than ODT?
I may have missed a decision and a reasoning about this, because of
the floods of threads there have been on the various lists over the
past weeks, so could you please excuse me if so and be kind enough to
briefly explain the adopted policies? Thanks if so...
I plan to work through the posted material and do some proofreading.

David Nelson

I am not very fluent in American English.
In defence many people do not recognise the calibre of the English language
and do not realise they make an arse of themselves, as a result require a
likeable counsellor.
I heard a rumour you were a wilful traveller trying to fulfil a furore with
the colour of your language, maybe you should go and analyse your arguments
in an encyclopaedia or maybe it is simply a tricky Manoeuvre on yo*ur part.*

My mum would be very dissapointed, it is her speciality.
She and I would be honoured if you would use the Queens English.

Michael Wheatland :slight_smile:

English documentation should be in International English, not US. When we
produce something for the International community, then an International
language should be used.

http://en.wikipedia.org/wiki/International_English

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?

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 may have missed a decision and a reasoning about this, because of
the floods of threads there have been on the various lists over the
past weeks, so could you please excuse me if so and be kind enough to
briefly explain the adopted policies? Thanks if so...

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:

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.

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

Fine.

Nino

Hi Micheal, :slight_smile:

I heard a rumour you were a wilful traveller trying to fulfil a furore with
the colour of your language, maybe you should go and analyse your arguments
in an encyclopaedia or maybe it is simply a tricky Manoeuvre on yo*ur part.*

??? I'm mystified... what does that mean?? :smiley:

My mum would be very dissapointed, it is her speciality.
She and I would be honoured if you would use the Queens English.

Sure. I understand you, but unfortunately you're likely to be
disappointed, I'd say... Already what I saw of the Getting Started
guide is US spelling... And, in my experience, most non-English
speakers tend to prefer learning US English (French and Germans, for
instance)... But I'm not bothered. Whatever the documentation team
feels is better.

English documentation should be in International English, not US. When we
produce something for the International community, then an International
language should be used.

Sure... Do you have an International English grammar book laying down
internationally-agreed conventions? :wink:

This is one of those old arguments that never ends. :smiley:

I guess the documentation team lead's wisdom will prevail in the matter... :slight_smile:
I don't mind either way. :slight_smile:

0.2 cents.

David Nelson

Sure... Do you have an International English grammar book laying down
internationally-agreed conventions? :wink:

sure do...

try these:

http://siteresources.worldbank.org/TRANSLATIONSERVICESEXT/Resources/Translation_Style_Guide_English.pdf

http://ec.europa.eu/translation/writing/style_guides/english/style_guide_en.pdf

http://books.google.com/books?id=r1bdk0YcPVsC&dq=international+english+guide&source=gbs_navlinks_s

Hi, :slight_smile:

Sure... Do you have an International English grammar book laying down
internationally-agreed conventions? :wink:

sure do...

try these:
http://siteresources.worldbank.org/TRANSLATIONSERVICESEXT/Resources/Translation_Style_Guide_English.pdf
http://ec.europa.eu/translation/writing/style_guides/english/style_guide_en.pdf
http://books.google.com/books?id=r1bdk0YcPVsC&dq=international+english+guide&source=gbs_navlinks_s

OK, cool, perhaps you could contact the guys who actually drafted the
documentation and enlighten them with the info... At the present time,
I'm just proofreading. But thanks for the heads-up. :slight_smile:

David Nelson

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