Tom Davies | 27 Aug 18:19 2014
Picon

Re: Re: User guides are not the only choice

Hi :)
I think wiki-editing is a little beyond many here but at least it's less of
a leap!  I think a few people have had some practice at it by working on
the Faq;
https://wiki.documentfoundation.org/Faq

So people who are new to wiki-editing can be fairly confident of getting
help&advice or hints&tips from a few more of us here - and of course we can
probably point people to external documentation to help further.

From what i hear the people who are working on the translators version of
the inbuilt help are doing a fantastic job and it would be great if that
could be supported a bit.

Alex had some great points earlier in the thread and i agree that his
talents are probably most needed in QA and development.  I think he did a
great job in kick-starting documentation about Base with his work on the
Faq section about Base.

I think that if we can give new people suggestions about where they start
then they can either follow the suggestions or not, either way is good.  At
the moment we tend to stand around and wait for them to figure it out,
which is not so good imo.  If we could push them towards the wiki  so that
they get practice and experience with wiki-editing then they will be
ideally placed to either;
1.  work on the in-built guide or
2.  move to the Published Guides after the logins have been sorted out for
them.
I think it would really help to give them something so that they can "hit
the ground running" rather than just keep them standing around waiting.
(Continue reading)

Sophie | 27 Aug 13:49 2014
Picon

Re: Re: User guides are not the only choice

Hi all,
Le 26/08/2014 16:13, Alex Thurgood a écrit :
> Le 26/08/2014 13:02, Tom Davies a écrit :
> 
> Tom,
> 
>> It would be great if people from this team could help get the translators
>> version into better shape, that might mean less geeky or might be that it
>> needs more reviewers.
>>
> 
> There already aren't enough people here on the documentation project in
> the first place to carry out regular and consistent work here - that is
> the point of Jean's other post - how can you legitimately now ask them
> to go and help out translating/reviewing the built-in help ?

For information, the en_US version (UI/Help) is currently maintained by
the l10n team, which is not optimal none of us being native English
speakers and most of us being alone to work on it's own language.
As you said, help is very difficult to maintain. So with Kendy and Moggi
working on it, we are trying to push it to the wiki help, to be
maintained and translated from here, there is still technical issues to
solve due to the structure or the current help files.
The wiki will not be open to every one to avoid too much extra work for
the l10n team, so there will be a reviewing process, just like there is
on gerrit.
Hi hope I'll be able to help to formalize the process and push it.
In this case, the Doc team could be part of the reviewing team too.
That will allow to share the work and get a better quality.

(Continue reading)

Tom Davies | 26 Aug 17:29 2014
Picon

Re: Re: User guides are not the only choice

Hi :)
Ah, i think that engaging with other things "raises awareness" of this
team.

For example, if the couple of people who are already working on (one of?)
the versions of the in-built help felt that there were people here who
understood something of what they do then they might join this group and
engage more with people here.  That sort of chatter might lead to the
in-built help being more consistent with the published guides, ie what
Peter was talking about.

Having people in this team using different tools might mean that new people
joining the team find something they can get involved in, that suits their
own skill-set.  At the moment there is only 1 way of working.  If new
people don't feel comfortable getting someone to register them at
ODFAuthors or feel uncomfortable with any part of working on the guides
then there is nothing for them to do except leave, or lurk.

Having different ways for people to get involved means people are more
likely to be able to join in and then maybe move around within the team
until they get comfortable doing something they enjoy.

Restrictions tend to lead to greater and greater restrictions ime.
Regards from
Tom :)

On 26 August 2014 15:13, Alex Thurgood <alex.thurgood <at> gmail.com> wrote:

> Le 26/08/2014 13:02, Tom Davies a écrit :
>
(Continue reading)

Tom Davies | 26 Aug 13:02 2014
Picon

Re: Re: User guides are not the only choice

Hi :)
The international translators focus on translating the inbuilt "Help".
There are a couple of people working on making that as good as they can get
it.  So i think that there might be more than 1 English version;  the one
that gets downloaded and the one the translators use.

It would be great if people from this team could help get the translators
version into better shape, that might mean less geeky or might be that it
needs more reviewers.

A very few translator teams are kinda working on translating the guides but
it's much lower priority than the in-built help.
Regards from
Tom :)

On 26 August 2014 08:24, PeeWee <psauthor <at> libreoffice.org> wrote:

> Hello Alex
>
> I do understand the problem about getting information from developers,
> especially after 30 years in technical publications. Maybe one day
> developers will understand that they have to help the users actually use
> the product, probably when I have finally retired (being a pessimist now).
>
> Good user guides and good help systems are a benefit to users and would
> reduce costs in supporting a product.
>
> After using Version 4.2 to create the Impress Guide, I think the Help has
> improved and does look a little more professional. Not perfect, but a step
> in the right direction.
(Continue reading)

PeeWee | 26 Aug 09:35 2014

Re: Draw Guide Version 4.3

Hello

Correction to the Draw Guide Preface (Chap 00) is now in the Drafts LO4.3
folder on the ODF Authors website. The correction was to the licensing
details for LO.

http://www.odfauthors.org/libreoffice/english/draw-guide/draft-lo-4.3/dg-lo4-3-chap-00-preface/view

Regards

PeterS

-----
Peter Schofield
psauthor <at> libreoffice.org
--
View this message in context: http://nabble.documentfoundation.org/Draw-Guide-Version-4-3-tp4120004p4120272.html
Sent from the Documentation mailing list archive at Nabble.com.

PeeWee | 26 Aug 09:24 2014

Re: User guides are not the only choice

Hello Alex

I do understand the problem about getting information from developers, especially after 30 years in
technical publications. Maybe one day developers will understand that they have to help the users
actually use the product, probably when I have finally retired (being a pessimist now).

Good user guides and good help systems are a benefit to users and would reduce costs in supporting a product.

After using Version 4.2 to create the Impress Guide, I think the Help has improved and does look a little more
professional. Not perfect, but a step in the right direction.

I have no experience at all in creating help files, so I shall not be volunteering my services. I am a book person.

Regards

PeterS

On 26 Aug 2014, at 09:06, Alex Thurgood [via Document Foundation Mail Archive]
<ml-node+s969070n4120266h5 <at> n3.nabble.com> wrote:

> Le 26/08/2014 07:58, PeeWee a écrit : 
> 
> Hi Peter, 
> 
> > 
> > In my opinion, the user guides and Help are the starting point for any other documentation/information
about using LibreOffice. So, anybody who works on other documentation should check the user guides and
Help so that the information is the same across all documentation. 
> > 
> > When writing the Impress and Draw Guides, I did check the Help of each module to make sure that information
(Continue reading)

Alex Thurgood | 26 Aug 09:06 2014
Picon

Re: User guides are not the only choice

Le 26/08/2014 07:58, PeeWee a écrit :

Hi Peter,

> 
> In my opinion, the user guides and Help are the starting point for any other documentation/information
about using LibreOffice. So, anybody who works on other documentation should check the user guides and
Help so that the information is the same across all documentation. 
> 
> When writing the Impress and Draw Guides, I did check the Help of each module to make sure that information
was reasonably consistent. It is not perfect and could be improved.
> 

The problem with relying on the built-in Help is that it is either
wrong, obsolete, or incomplete, especially where new features are
concerned.

Currently, writing help files for the built-in Help system is an utter
nightmare, and involves being knowledgable in, and having the time to,
wade through a vary unwieldy set of XML conventions. The end result is
that no one wants to edit the Help files to keep them up to date.
Additionally, we encounter the well known phenonemon of developer
reticence about explaining how to actually use the new feature for which
they've just coded. Getting developers to provide meaningful code
comments is hard enough, because each has their own view on how much any
given other developer should be capable of understanding. None, as far
as I know (and I'm prepared to stand corrected), other than those
working on the Help system itself, have ever written an XML help file
for the built-in Help system.

(Continue reading)

Jean Weber | 26 Aug 03:18 2014
Picon

User guides are not the only choice

For those people who find working on the user guides a bit daunting,
for whatever reasons, there are other possibilities for user
documentation: how-to's and tutorials (both written and video), "tip
of the day/week/month" type blog posts (yes, we have a blog), material
on the wiki instead of or in addition to ODT/PDF/print, and I'm sure
you can think of others. Some of these may overlap with what's being
discussed and worked on through the Marketing list.

If you're interested in doing something, let us know. Just because the
small active group has time and topic priorities, that doesn't mean
you must fit in with those, no matter what the opinion of some
individuals who post to this list.

--Jean

--

-- 
To unsubscribe e-mail to: documentation+unsubscribe <at> global.libreoffice.org
Problems? http://www.libreoffice.org/get-help/mailing-lists/how-to-unsubscribe/
Posting guidelines + more: http://wiki.documentfoundation.org/Netiquette
List archive: http://listarchives.libreoffice.org/global/documentation/
All messages sent to this list will be publicly archived and cannot be deleted
Jean Weber | 26 Aug 02:49 2014
Picon

Coordination, mentoring, etc

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

--

-- 
(Continue reading)

Jean Weber | 25 Aug 23:25 2014
Picon

Re: Fwd: Impress Guide Version 4.2

On Mon, Aug 25, 2014 at 10:27 PM, Tom Davies <tomcecf <at> gmail.com> wrote:
> Hi :)
> Ahh, so a list of "suggested things to work on" might be helpful?

It might be helpful, but someone has to do it and keep it up to date;
sometimes the list would change rapidly. And I'm not the someone to
take care of such a list (I am capable, but I don't).

Also, Hazel said 'I feel more comfortable if someone drops me a line
saying "This needs doing now and you are the obvious one to do it."'
-- that is not the same thing as having a list. I often, though not
consistently, do write to her about things to do.

> I keep being told that such a thing is impossible and that people would
> reject any such manipulation anyway and just go off and do their own
> thing.

Having a list is not "manipulation" but people will do their own thing
and/or not choose the most urgent items on the list. Example: I choose
not to create and update a list, no matter how important others may
think it might be.

> Wrt the Calc chapters done by Jean there does, of course, need to be
> someone quite knowledgeable about the Guide's topic involved at some
> point(s) in the process.  However there also needs to be non-experts
> involved, preferably noobs to the topic, because otherwise the guides run
> the risk of being too geeky and unhelpful to non-experts.  Of course now
> that Jean has worked so intensely on those Calc chapters it makes he more
> of an expert than she had been previously so it's difficult to make sure
> the team keeps getting the fresh perspective.  I thought the review process
(Continue reading)

Jean Weber | 24 Aug 23:51 2014
Picon

Re: Fwd: Impress Guide Version 4.2

Tom,

Hazel cannot proofread the remaining chapters of the Writer Guide
until someone updates them, so suggesting that she skip proofing the
Impress Guide in favour of Writer is irrelevant.

You seem to be perpetually of the erroneous opinion that all the work
that needs to be done on the various books is interchangeable: that
any volunteer can do whatever needs doing next, if only they knew what
it is. This is wrong and unhelpful. If someone doesn't feel competent
to work on updating, say, the Calc Guide, they won't do it... or if
they do, they'll likely get it wrong. I mention the Calc Guide because
I wrote a lot of the later chapters (not knowing much about
spreadsheets in general or Calc in particular) and those chapters need
more knowledgeable people to improve them.

As for the Writer Guide... where is everyone? The remaining chapters
cover fairly straightforward features that fewer people use, so a
volunteer who isn't familiar with them can still be quite helpful
going through the chapters and seeing if anything has changed in the
program or the instructions are unclear, or whatever.

--Jean

On Mon, Aug 25, 2014 at 2:54 AM, Tom Davies <tomcecf <at> gmail.com> wrote:
> Hi :)
> I have complete faith in both Peter and Jean (errr, and you Hazel).
>
> Proof-reading probably does usually need to be a separate process but in
> this particular case i think skipping it and going straight to the few
(Continue reading)


Gmane