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

Hello

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.

Regards

PeterS

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.

All of this makes it very hard to write accurate, up to date user
documentation, but the problem in itself isn't new, merely exacerbated
by the frenetic pace of development.

Alex

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

Hi :slight_smile:
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 :slight_smile:

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 ?

Alex

Hi :slight_smile:
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 :slight_smile:

Hi all,

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.

Kind regards
Sophie

Hi :slight_smile:
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.

Sorry if that is a bit harsh! I think everyone here is doing a fantastic
job and that we just have to find ways to make the most of that -
preferably without anyone needing to do any more than they already do!
Regards from
Tom :slight_smile:

I don't think anyone here thinks that giving people suggestions is a
bad idea. But if no one does it, then it doesn't get done (to state
the obvious, once again). And it helps if the whoever is doing it has
a good idea of what's feasible and necessary in terms of the project,
the tools available, and technical communication in general.

I know at least one person who is suitably experienced and
knowledgeable and would IMO do a very good job for this team, but that
person needs to earn a living and so isn't available to take on the
job unless it's paid.

--Jean