General questions and suggestions

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

Marc, please do! And I, at least, did not take your comments negatively.
I agree with all you said, and you said it well.

--Jean

[...] 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.

not sure what you mean by having "a direct feed to the devs" (I'm not a
native speaker so sometimes I have to ask for better understanding,
sorry)

I think we should roughly catch requirements, then ASAP pick and provide
appropriate tools and start working as soon as possible. Fine tuning
can be done successively, as all parties will be learning by doing.
Call it prototyping or similar, I'm not an expert here.

What better way to prove that your tool if built for complete
document production from start to finish.

The tool has to be adequate/appropriate. For Internet collaboration,
mere ODF is not (yet) good enough, wiki and web are far more
appropriate. But nonetheless, it's a challenge to set up appropriate
workflows and supportive tools (and BTW that's one of the reasons for
me to participate here).

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

Don't forget that we are setting our constraints ourselves :slight_smile:

N.

I'll add that using the OOoAuthors website to produce LibO docs does NOT
mean that the LibO docs team is required to follow the procedures we use
for producing OOo docs. Indeed, I think some of the native-language
groups using the website follow slightly different processes from those
used by the English-docs team.

Also there is nothing to prevent the LibO docs team from switching (if
they choose to) from using the OOoAuthors website to using the Document
Foundation's site when it's up and running, doc procedures tested, and
so on.

IMO the team should use the most efficient methods available now to get
out the first release of user guides ASAP, and then refine methods as we
go along. Same for fonts and other issues like whether or not to use
heading numbering. With a properly set up template, fonts and heading
numbering and other changes can be made quickly and easily at any time.

--Jean

Thanks for the info.

Cheers

Marc

Thanks.

Marc

In that case, why not a Canadian version as well.

I will be converting every document into Aussie!

Just a taste:
"G'day, this is the bonza Libra Office kick off guide, grab a beer and start
typing!"

Michael Wheatland

Mate, getting the name of the product correct would be a good idea,
regardless of the dialect into which a document is localised.
*LibreOffice*

--Jean
(waving from Townsville, North Queensland)

Just a play on our pronunciation of the word Libre (Libra, like the
way we say Litre)
By the way, I am not far away from you, just over the gulf in Nhulunbuy.

Just a play on our pronunciation of the word Libre (Libra, like the
way we say Litre)

You say "litra"? I knew you Territorians talked funny, but I don't
recall hearing that one before. I learn something new every day!

--Jean

Jean Hollis Weber wrote:

I'll add that using the OOoAuthors website to produce LibO docs does NOT
mean that the LibO docs team is required to follow the procedures we use
for producing OOo docs. Indeed, I think some of the native-language
groups using the website follow slightly different processes from those
used by the English-docs team.

Well, the Italian team for instance only translates the published
English chapters, so it's expected that their processes are different.
In our case, the volunteers' choice was to base on the English ODT
version.

We thus have:
- English ODT -> English Wiki (through the "Wiki Publisher" extension)
- English ODT -> Italian ODT (through OmegaT and translation memory)
- Italian ODT -> Italian Wiki (through the "Wiki Publisher" extension)
- English Wiki -> Italian Wiki is forbidden

This, thanks to translation memories, proved to be the best workflow
when updates are concerned; and, if someone is going to adapt the
OpenOffice.org documentation to LibreOffice, this might be a good
approach to minimize the volunteers' efforts.

Regards,
  Andrea Pescetti.

Thanks Andrea, we will make a note of it for the Drupal setup.

Marc

BTW ... let us know if you need any other customizations and we will look into it as well.

Cheers

Marc

Hello,

I must confess that I read the thread fairly quickly so I may have missed some points, but here we go with my observations.

Language
It has to be en-US since, at least for OOo, this is the default language and the one you get in addition to the localized version.
Though I would like to see colour, metre, centre written correctly :wink: I think you can live with this choice.

File format
My preference is to use ODF.
No doubt that the wiki version is much more dynamic and better suited for a collaborative environment, but it also has drawbacks (review of entries, printing, tracking of the program version)

Workflow
There is another thread on this so to keep it short, I think we should stay with something similar to OOoAuthors based on
draft --> review --> publish
What is missing in OOoAuthors is a definition of the role of publisher / "editor in chief" that is the person(s) that decide when to pull the trigger and publish. At present Jean takes care of this (and does a great job) but if it wasn't for her dedication I do not know how a document would be deemed ready for publishing.
So some work to do there.

Template
I guess it does not make much sense to depart from the template used by OOoAuthors that over time has been refined and improved.
You may want to consider making better use of colours, adding heading numbers, make it more modern-looking but I am not sure that should be a priority unless you want to give the LibO guides their own identity from the start.

Cheers,

Michele

Hello,

I must confess that I read the thread fairly quickly so I may have missed some points, but here we go with my observations.

Language
It has to be en-US since, at least for OOo, this is the default language and the one you get in addition to the localized version.
Though I would like to see colour, metre, centre written correctly :wink: I think you can live with this choice.

File format
My preference is to use ODF.
No doubt that the wiki version is much more dynamic and better suited for a collaborative environment, but it also has drawbacks (review of entries, printing, tracking of the program version)

Workflow
There is another thread on this so to keep it short, I think we should stay with something similar to OOoAuthors based on
draft --> review --> publish
What is missing in OOoAuthors is a definition of the role of publisher / "editor in chief" that is the person(s) that decide when to pull the trigger and publish. At present Jean takes care of this (and does a great job) but if it wasn't for her dedication I do not know how a document would be deemed ready for publishing.
So some work to do there.

Template
I guess it does not make much sense to depart from the template used by OOoAuthors that over time has been refined and improved.
You may want to consider making better use of colours, adding heading numbers, make it more modern-looking but I am not sure that should be a priority unless you want to give the LibO guides their own identity from the start.

Cheers,

Michele

Hi Jean, :slight_smile:

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).

Sorry about the "old timer" :wink: but please read my loose use of the
term to mean "highly-experienced and respected contributor". It didn't
click that you're in fact a lady either because, unfortunately, there
are far too few women involved in Open Source projects. <rant> If
there were, there would probably be a lot more actual work done and a
lot less unproductive blowing-off of air in mailing lists. :wink: I've
worked with women engineers before, and they tend to be pragmatic,
practical and go straight for the shortest and simplest route to the
intended goal. </rant> :slight_smile:

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.

I regret a great deal that you won't be the documentation lead for
LibO. But I hope that I may have the opportunity to draw on your
wisdom and experience, as I'm new to the project and am engaging on a
learning curve as I familiarize myself with its methods and practices.

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.

I'm a Brit myself but, certainly at the moment, it seems more
realistic to target getting a comprehensive set of documentation in
*one* variety of English. So maybe "International" English with US
spelling is the best option at this time. Perhaps when the LibO
project is at a more mature stage, there will be manpower to do
localized documentation for Australia and New Zealand, Canada, the UK,
the US...

As regards punctuation, when I write professionally, I like to use
punctuation that conforms to formal grammatical parsing, like as wot
Winston Churchill sed.

Anyway, for the proofreading that I've started, I'd be really grateful
if you could maybe watch this thread, where I'll be posting a few
questions:

http://www.libreoffice.org/lists/documentation/msg00172.html

A big thanks if so. :slight_smile:

David Nelson

Hi Jean, :slight_smile:
Sorry about the "old timer" :wink: but please read my loose use of the
term to mean "highly-experienced and respected contributor".

Don't worry, that's the way I read it. :slight_smile:

Anyway, for the proofreading that I've started, I'd be really grateful
if you could maybe watch this thread, where I'll be posting a few
questions:

http://www.libreoffice.org/lists/documentation/msg00172.html

A big thanks if so. :slight_smile:

Thanks for the reminder that your version is more recent than Ron's.
I'll collect the latest from the wiki. And if I have any comments, I'll
put them on that thread, as you requested.

To avoid confusion, it might be a good idea to put the latest version on
the OOoAuthors site as well as on the LibO wiki.

--Jean

Hi, :slight_smile:

Thanks for the reminder that your version is more recent than Ron's.
I'll collect the latest from the wiki. And if I have any comments, I'll
put them on that thread, as you requested.

OK, thanks. :slight_smile:

To avoid confusion, it might be a good idea to put the latest version on
the OOoAuthors site as well as on the LibO wiki.

OK, I'll post my stuff on both sites... Are there any plans to work-up
a harmonized workflow to eliminate redundancy? IMHO, it would be great
if we were all on the same page as one happy team. :slight_smile:

David Nelson

If I were to get picky, picky... The CMoS says not to hyphenate adverb-adjective combinations whose adverbs end in -ly. So, it should be: "highly experienced" instead.

Gary