Coordination, mentoring, etc

Documentation General
#1

IF people in this group think some coordination and/or mentoring is
needed or at least would be useful, the group needs to find someone or
several people to do that, do it consistently, and do it well.

I do a bit now and then, but I have not been doing it consistently,
have no intention of doing it consistently, and will probably be doing
even less in future. I've been saying this for months, but is anyone
listening?

If we can't find one or more volunteers to take on this sort of
responsibility, perhaps we should make a case for TDF to fund someone,
at least part time? IMO we would need to hire someone with experience
in technical communication, project management, and mentoring new team
members. Preferably someone with experience coordinating volunteers,
so they don't have inappropriate expectations of giving people
assignments and getting the work done to a schedule. (No, I'm not
looking for a job.)

I'm not at all sure that would help enough, because we would still
need people who have both the time and knowledge to do the actual
work. Our problem, AFAICT, has not been in attracting volunteers. The
problem is attracting -- and keeping -- the right volunteers: that is,
people with the time and knowledge.

BTW, I find it both encouraging and discouraging to note that the AOO
Docs group appears to have the same problems that we do.

--Jean

#2

Hi Jean,

I'm not at all sure that would help enough, because we would still
need people who have both the time and knowledge to do the actual
work. Our problem, AFAICT, has not been in attracting volunteers. The
problem is attracting -- and keeping -- the right volunteers: that is,
people with the time and knowledge.

I agree. Volunteers need both time and continued enthusiasm - I have
little time, and my own personal enthusiasm for writing/translating
documentation has waned as I have seen that it is impossible to keep up
with the pace of development and/or the new bugs that are introduced as
a result of that development. Ultimately, how one feels about the
quality of a product affects one's enthusiasm to write stuff about it.
This has caused me to focus on working on QA, rather than documentation
- after all, if the product doesn't work as intended, why not try and
get it fixed (sometimes a vain hope) rather than attempt to write
documentation which, when released, will essentially/probably be out of
date and/or inaccurate ? By the way, this is not a plug to draw people
from the doc project to QA, just my personal experience !

Documentation needs a solid base from which to work - IMO, this means
that the software shouldn't be changing its product characteristics and
features every 6 months (or less) - if you don't have that, the efforts
that go into creating and maintaining documentation for the product
imply relying on a massive documenter group to keep up and currently,
the LO documentation project doesn't have that critical mass.

Alex

#3

Hi Jean

I agree with you. My problem, coming recently to volunteering, is that it's
hard to actually know what to do. Some mentoring or at least direction
relating to tasks would be most useful, even though it seems to go against
the grain of 'volunteering'. By the same token, rigidity is no good;
volunteers have other lives to lead and sometimes those lives take over.

I'm staging a return to authoring after an absence of some years, and
volunteering for documentation tasks seems a good way to build up recent
experience on my CV. However, I need to specifically identify and access
the tasks there are in the Libre Office Documentation team and, you know,
that's a bit of a problem for me right now. So mentoring and a bit of steer
would be most welcome!

Regards

Tony

#4

just a thought...could all contributors introduce themselves and what aspects of the doco they work on?

I am not a qualified author and my knowledge of LO is largely gleaned from this mailing list (and reading the documentation). I therefore try to proof read docs when they come out - been a bit lazy of late :frowning:

Cheers

#5

Hi :slight_smile:
It is something that people try to do when they join the team but it might
be nice to hear from a few people who have been here a while.

Me, i am just a lurker here.

It helps me deal with other issues on other mailing lists or with questions
outside of the on-line community. I try to bring back feedback i have had
from elsewhere or suggestions from various places but all that is mostly
interpreted as trolling.

I try to "promote" this team (or raise it's profile or whatever other weird
way people have of describing it) on the Users Mailing List, especially at
times the devs have been promoted or when people seem to want to know how
to contribute back to LO. I get flak for that too but the users seem to
appreciate it, especially if i spot someone who might be good here and am
able to (off-list) directly invite them.

Regards from
Tom :slight_smile:

#6

You don't get "flak" for promoting the group. You get flak for being
quite negative and sometimes insulting when you do the promotion.

--Jean

#7

Hello all,

I'm updating the English translation of the Base Handbook from 3.5 to 4.2, and have run across a problem concerning which I'd appreciate some advice and feedback.

In Chapter 3, "Tables," the section following the heading *Creating Tables/Creation using the GUI* begins as follows:

"Database creation using the GUI is described in detail in Chapter 8, "Getting Started with Base," in the /Getting Started with LibreOffice/ book. Therefore only the main sources of error are described here."

The problem is that [the first sentence of] that statement is just plain false.

The GUI offers two ways of creating tables: Use Wizard to Create Table and Create Table in Design View. The /Getting Started/ chapter only provides instructions for using the Wizard. The Wizard only provides database templates with preexisting table and field names. If you want to design a database for any purpose other than the ones that the templates cover, it's useless.

So far as I can tell, there are no instructions provided anywhere in our documentation on how to create a table in Design View, which seems to me to be the method that most users are likely to use. (I could well be wrong about this, but if those instructions exist, they aren't located in the most logical place to look for them.)

Moreover, the /Getting Started/ chapter explains only how to create a flat, single-table database. (I'm not sure why you'd want to do that rather than just use a spreadsheet, but . . . .) The material in the handbook, on the other hand, assumes that you're building a relational database with multiple tables.

The reason I can't just ignore the problem is and go on is: The section that follows this introduction contains some new material in the German that needs to be translated. Translated super-literally, it doesn't make much sense. Good technical instructions are directed at the particular situation in which the user is going to need those instructions and tailored to the user's preexisting knowledge. That context is exactly what the current text doesn't provide, and what I need in order to put this stuff into comprehensible English.

Any and all advice appreciated.

Thanks,
Alan

#8

Hi Alan,

hope I understand most you have written the right way. My
English-knowledge is "very special".

I'm updating the English translation of the Base Handbook from 3.5 to
4.2, and have run across a problem concerning which I'd appreciate some
advice and feedback.

In Chapter 3, "Tables," the section following the heading *Creating
Tables/Creation using the GUI* begins as follows:

"Database creation using the GUI is described in detail in Chapter 8,
"Getting Started with Base," in the /Getting Started with LibreOffice/
book. Therefore only the main sources of error are described here."

The problem is that [the first sentence of] that statement is just plain
false.

I have written most of the Base-Handbuch. The "Getting Started with
Base" in German isn't the same as in English. Could be better to delete
anything which relates to "Getting started ..."

And this is a special problem with most of the content here. Creating a
Database with wizards (incl. queries, forms ...) and creating databases
directly by using the GUI is declared in the German "Getting started
..." This problem will be solved a littel bit with the German
Base-Handbuch 4.3. There is a example added. For the English
Base-handbook it would be better to add the German "Getting-started" as
attachment to the Base-handbook.

Regards

Robert

#9

Hi :slight_smile:
Ahh, i thought this was going to be done by only re-translating the bits
that changed rather than starting from scratch each time? I think starting
from scratch occasionally might be a good idea to make sure everything
really is covered.

Now the question is whether to do the polishing off to Hazel's work on the
4.2, or abandon that or to update her work for the 4.3 and then do the
polishing off after the updating is done.

I thought we had just agreed that the only change between the 4.2 German
Handbook and the 4.3 is the addition of just 1 more full example?
Regards from
Tom :slight_smile:

#10

Hi Tom,

Ahh, i thought this was going to be done by only re-translating the bits
that changed rather than starting from scratch each time? I think starting
from scratch occasionally might be a good idea to make sure everything
really is covered.

Now the question is whether to do the polishing off to Hazel's work on the
4.2, or abandon that or to update her work for the 4.3 and then do the
polishing off after the updating is done.

I thought we had just agreed that the only change between the 4.2 German
Handbook and the 4.3 is the addition of just 1 more full example?

It isn't a problem of the Version 4.2 of Base Handbuch. It's also a
problem of version 4.3 - the links to "Getting started ..." are also in
this version.

I will try to solve this with the next version of the Base Handbuch. I
will put some content of the German "Getting Started" in the
Base-Handbuch and will delete the links to "Getting started".

When I wrote the Base-Handbuch I have never thought it would be
translated and would only be a part of the German documentation. Had
also never thought someone will print a book of it...

Regards

Robert

#11

Option # 1: Write how to create a database using Design view, wizard, and whatever the other mode is;

Option # 2: Include one line stating that it is assumed that the user knows how to do whatever is missing from the documentation, but to which explicit reference is made;

My recommendation is Option # 2.

jonathon

#12

I failed to send this to the list.

#13

I failed to send this to the list.

#14

I failed to send this to the list.

#15

Tom, please pay attention. Alan found a problem with references to the
Englsih Getting Started guide, which he did not realise has changed in
GSv4.2. Starting from scratch translating either the German 4.2 or 4.3
Base Handbook into English would not solve the problem because
references from the Base Handbook to the Getting Started Guide would
still be wrong.

I have just forwarded to the list three notes that I had written
earlier but failed to send as reply to all; instead I replied only to
Alan, so everyone else won't have seen them. In the third I mention
where the previous version of the Getting Started chapter is now
located, renamed as a tutorial.

Robert, does the previous English GS chapter, which is now available
as a tutorial, cover the missing info? If so, Alan can just change the
references from GS to the tutorial. Or we could include that tutorial
in the Handbook as an Appendix; that would work too, perhaps better
than sending people to a separate document. But either of those
solutions depends on whether the tutorial covers the necessary info.

--Jean

#16

Hi Jean,

Robert, does the previous English GS chapter, which is now available
as a tutorial, cover the missing info? If so, Alan can just change the
references from GS to the tutorial. Or we could include that tutorial
in the Handbook as an Appendix; that would work too, perhaps better
than sending people to a separate document. But either of those
solutions depends on whether the tutorial covers the necessary info.

Have downloaded
http://wiki.documentfoundation.org/images/1/13/GS40-GettingStartedLO.pdf.
The Base-chapter is the content, which would be missed in the
Base-handbook (for example: "Creating tables in Design View").
So a link to "Chapter 8 - Getting started with Base" would work also for
Base-Handbook 4.2.

I will find a better solution in the next Base-Handbuch by copying the
missed parts of the German "Getting started ..." into the chapters of
the Base-Handbuch. Haven't seen the Base-Handbuch as a standalone-book.
Thought it was a continuation of "Getting started".

Robert

#17

Whew! I'm afraid it's going to take me a little while to process this whole discussion. Thanks, everyone, for your input.

Alan

#18

Hi :slight_smile:
Yeh, sorry! I thougth we had 2 people working on the Base Handbook and
that 1 of those was duplicating work that has already been done by Hazel
where nothing new has been added since Hazel did her translation.

I didn't realise that redoing work that has already been done was not the
problem and that it was ok to carry on redoing all the rest of the work
that has also already been done.
Regards from
Tom :slight_smile:

#19

Hi :slight_smile:
I think that rather than carry on with the 4.3 it might be better to carry
on from where people have already gotten up to with the 4.2.

Unless translation is really what you want to do in which case finding the
1 chapter that has been added and translating that might be really good.
Regards from
Tom :slight_smile:

#20

Hi Jean, all,

Sorry to not have post before but I was focusing on the LibreOffice
conference and wanted to have time to read the mails of the list.
So I would like to volunteer to coordinating the work on this project.
For those who don't know me, I'm with LibreOffice since the beginning of
the project, I'm working for TDF on a paid basis as release coordinator and
administrative assistant. On my volunteer time, I used to localize the UI
and help of LibreOffice in French, do some QA, and translated some part of
the FAQ from French to English. My English is not good enough to write the
English documentation, but I quite well know all the parts of this project
to be able to help his coordination and help new comers to find their way.

Let me know if you would like me to help on this task :slight_smile:
Kind regards
Sophie

Impressum (Legal Info) | Datenschutzerklärung (Privacy Policy)   Content on this site is licensed under a Creative Commons Attribution Share Alike 3.0 license.