![[TEST] Document Foundation Community](https://communitytest.documentfoundation.org/images/discourse-logo-sketch.png){kind=logo}
Hi All,
I'm an experienced Technical Writer beginning work on LibreOffice's
documentation, but I have some questions for LibreOffice users:
1) Does anyone EVER look at the pdf documentation? If not, why not?
2) Does anyone EVER click the F1 key for help? If not, why not?
3) Do you see any overall issues concerning the documentation?
4) If the presentation of the documentation were to change to make it
more useful, what would it look like?
Thanks for anyone's help.
Davidaa
Hi All,
I'm an experienced Technical Writer beginning work on LibreOffice's
documentation, but I have some questions for LibreOffice users:1) Does anyone EVER look at the pdf documentation? If not, why not?
I have occasionally used the PDFs
2) Does anyone EVER click the F1 key for help? If not, why not?
Yes.
3) Do you see any overall issues concerning the documentation?
4) If the presentation of the documentation were to change to make it
more useful, what would it look like?
Epub as well as PDF would be nice.
Hi All,
I'm an experienced Technical Writer beginning work on
LibreOffice's
documentation, but I have some questions for LibreOffice users:
1) Does anyone EVER look at the pdf documentation? If not, why
not?
I have occasionally used the PDFs2) Does anyone EVER click the F1 key for help? If not, why not?
Yes.
3) Do you see any overall issues concerning the documentation?
4) If the presentation of the documentation were to change to makeit
more useful, what would it look like?
Epub as well as PDF would be nice.
Thanks for anyone's help.
You may want to contact the documentation team as well - and perhaps even join them: http://www.libreoffice.org/get-help/documentation/
Best,
Charles.
Davidaa
--
View this message in context:http://nabble.documentfoundation.org/LibreOffice-s-documentation-pdf-and-online-tp4152516.html
Sent from the Users mailing list archive at Nabble.com.
Hello David,
Hi Charles,
Thanks for taking the time.
I just want to clarify:
I have joined the documentation team already and am working with them.
What I'm looking for is feedback from users. It's easy for writers to write
what they want to write or what they find useful. What I want to know is
how users feel about the documentation.
Thanks,
Davidaa
Here are my responses.
1. I seldom look at the PDF documentation. Mostly I find what I need through the F1 key, and also because I forget it's there until I go searching for an answer online. I'll also go to the PDF when I'm trying to understand an entire concept (like styles, which still are winning the battle).
2. I use the F1 key all the time. I came to LO after using Windows since it was created and F1 is the first thing I do to get help on any program. It's nice when it's context-sensitive, but just going to the built-in help is sufficient.
3. Most of the time I'm using any documentation it's via the F1 key (or the menu equivalent, if I already have my fingers on the trackpad) and I'm usually coming from a spreadsheet, looking for the parameters for a specific function. This is one of the few areas where in my experience MS Office is actually superior to LO; in MSO the functions are grouped better for ease in finding what you're looking for (arithmetic functions, logical functions, etc.). In the LO help you often have to know what function you want to use, even if what you're looking for is what function fits your current need -- like having to know how to spell a word before you can look up its spelling in the dictionary.
4a. Some have suggested videos. Personally, while I have no trouble with either my vision or my hearing, I hate the trend toward doing everything on videos. They take longer than reading, they annoy other people in the office, and usually they're not the best choice for what I need at the time. They might be useful for longer topics (like those blasted styles), but not for syntax questions, for example.
4b. My preference is for a manual's information to be available locally. I'm not always in a location with Internet access, and sometimes I turn off my modem because I don't want any new mail downloaded (I have 18 mailboxes to manage, and if I close the email program before I check them all then the new messages are no longer flagged as new; unread isn't a sufficient status).
Thanks for asking for our input. I've rewritten seven sets of bylaws for various organizations, so I don't envy you and the rest of the volunteers on this project!
Dave Liesse
I can only speak for myself, I don't know what others do, but for programs
or devices that require documentation, I download the pdf file and print it
out, and put the document into a 3-ring binder dedicated to that application.
I would sincerely hope that the file would have an excellent index. I am much
more comfortable with paper documentation that I can have in front of me
while I am looking at the program on screen, or the physical device.
As to LibreOffice, I gave up on it some time ago. The program is far too
complicated for a word processor. I believe that it attempts to be a desktop
publisher, and I am not looking for that kind of complexity. It hardly compares
with something like WordPerfect or TextMaker (from SoftMaker), either of
which is much more transparent to the user.
If I had to guess, my guess is that most people trying to use LO do not know
about finding help under the F1 key. In my experience many (but not all) programs
that claim to provide help do not answer the question that brought the user to
the help screen. Either the help documentation is too sparse, or it is poorly
indexed, or perhaps both. I do not speak for LO, as I don't normally use it,
and I am one of the people who never knew about the F1 key. I would not go back
to LO anyway, because of its unnecessary complication.
The one instance where I find LO useful is its capability of reproducing
graphic material cut and pasted from some online site, so that the material
can then be printed out with the graphics. This, of course, does not require
any editing, so avoids the complication.
In spite of my dislike of this particular app, I hope my comments in answer to
your questions have been helpful.
--doug
Microsoft program specifications have defined <F1> as the help key for
at least two decades.
jonathon
Ah... So, it's fairly new then. 
Ding! Ding! Hello!
Who the heck do you think has been writing this stuff since 2001?
Short answer: USERS!!!
There is no "Documentation Team", only a tiny handful of USERS, who
occasionally step up to the plate and try to contribute something that
may be of help to our fellow USERS. Be assured that none of those
contributors only "write what they want to write or what they find
useful" and if they wanted "easy" they would not write anything.
To the best of my knowledge, only one of those USERS has professional
writing skills and without her tireless input from day one neither the
previous OOo project or LO would not have any usable documentation.
Of course it's possible to create documentation in the form of videos,
epub, slide presentations or any other "all-singing, all-dancing,
lights-bells-whistles-and-buzzers" media form anyone wants to add to
their wish list. There is just one tiny trivial problem, finding the
army willing volunteers to take on these tasks. Research is good, but
the research priority should be how to find and keep documentation
contributors.
Regards
Dave
Just to state the obvious - we have a documentation team - and they do a
ton of work including writing user manuals....to say anything else is
ridiculous.
Good morning from Japan
Well, I am a user and definitely NOT a computer specialist.
As such, I ALWAYS encounter this one particular "problem":
"What is the thing/situation I am struggling with called in technical (help file) terms?"
If you do not know what to ask, it is VERY difficult to find the answers in any form of documentation.
So, my "wish": include some form of cross referencing, that will allow you to find your answer, even if you
do not know the exact name of the thing you are looking for.
Something like: question = how to set an indent?
May also want to look at: paragraph, formatting, alignment, etc. ..... (preferable with links to the relevant sections).
Does that make any sense, or am I the only one having trouble finding my way around?
Thomas
To the best of my knowledge, only one of those USERS has professional
writing skills and without her tireless input from day one neither the
FWIW, several of the people on the Documentation Team, published books
and other material, prior to volunteering on the documentation project.
Of course it's possible to create documentation in the form of videos,
What happened to the people that were creating documentation in video
format?
That said, I've periodically looked at creating video documentation, and
realized that it is much simpler, and easier, to create a PDF, than to
create the video.
Perhaps what is needed, is an individual, or team, that can pick up the
documentation in ODF format, convert it to a storyboard, and then create
the video.
epub,
The major reason the documentation is not also available in ePub format,
is because there have been precious few requests for it to be in that
format. Nonetheless Jean has modified the template used by ODFAuthors,
so that export to ePub format is more reliable, consistent, and
professional looking. (You still have to manually strip out all of the
<span> markup code in the resulting ePub.)
slide presentations
What happened to the people that were creating documentation, in the
form of slide presentations?
There is just one tiny trivial problem, finding the army willing
volunteers to take on these tasks.
Technically there are two issues:
* Finding people that are willing to do it;
* Excluding people whose legal residence is in a jurisdiction that
prohibits them to do these tasks, unless they are being paid to do so;
Research is good, but the research priority should be how to find and
keep documentation contributors.
We don't need research on how to find and keep documentation
contributors. (I'm not saying that the running average of new volunteers
is great.)
What is needed, is a reduction in the barriers that new contributors
face, in creating/maintaining documentation.
For starters, there are three different groups that are involved in
creating/maintaining documentation. Each group has its own templates,
set of procedures, priorities, and barriers to participation.
I'll take what should be a trivial task, that should not take more than
thirty seconds. Find and install xmlhelptemplate.ott.
The second, and what should also be a trivial task, is locating and
installing Helpauthoring.oxt.
Time how long it takes you to locate both of those files. Then time how
long it takes you to install them, assuming you can install them in the
first place.
That exercise explains why the built-in help is so wildly inconsistent
in quality.
With the documentation produced at ODFAuthors, the primary issue is,
quite literally, getting them started in the (¿easy?) things, like
proof-reading and copy-editing.
Something that isn't clear to most new contributors, is that whilst the
focus is on the six core manuals, there are a score of other manuals
that are on the wish-list.
The core manuals being:
* Getting Started;
* Base;
* Calc;
* Writer;
* Math;
* Impress;
* Draw;
The wish list consists of:
* Intermediate usage of those components;
* Advanced usage of those components;
* _Migrating from MSO to LibO_;
* _Site Administration of LibO_;
* _Creation and Distribution of Templates and Extensions_;
* _Using R in Calc_;
* _Project Management Using LibO_;
* _Accessibility and LibreOffice_;
I've forgotten the other topics.
There are also a dozen or so other documents, that would be useful, if
translated into English, and other languages.
The third group is the one that creates and maintains the online
documentation. The most urgent task needed there, which looks like, and
has been described as "an easy hack", is extremely complicated.
Related to the issue of Documentation, is the issue of Translation.
Most people don't realize that L10N teams are responsible for
translation of the UI, the Built-In Help, the documentation on the
website, and creating/translating user guides in the local language(s).
We aren't yet at the point where machine translation is as good a human
translation is.
jonathon
Hi all,
First, thanks to everyone for all the responses. They're really helpful; I
think I'm getting a picture of what is happening here. I hope more people
add their thoughts even if they're identical or similar to what has already
been said. Repetition will give more meaning.
Hi Jonathan,
"For starters, there are three different groups that are involved in
creating/maintaining documentation. Each group has its own templates,
set of procedures, priorities, and barriers to participation."
Three groups? 1) pdf 2) Online help
Who else?
Thanks,
Davidaa
also the "pdfs" (aka User Guides)
Nino
Built-in Help.
This is the group that uses those two files I described as "what should
be a trivial task to find and install."
And I think a case can also be made for the individual L10N Teams.
jonathon
Hi Davidaa
Hi all,
First, thanks to everyone for all the responses. They're really helpful; I
think I'm getting a picture of what is happening here. I hope more people
add their thoughts even if they're identical or similar to what has already
been said. Repetition will give more meaning.
You should also take into account that our community is international,
so the documentation may exist on different forms on the native language
projects.
The first documentation available to all users, whatever the language,
is the off line help, which is then duplicate to the wiki help. This
documentation needs much more love and is more and more outdated. We are
aware of it and would like to set a group to work on it. That is what
Jonathon has explained.
The l10n group is doing the QA on the UI and the off line help of the
en_US version. Some of them produce also help articles.
Hi Jonathan,
"For starters, there are three different groups that are involved in
creating/maintaining documentation. Each group has its own templates,
set of procedures, priorities, and barriers to participation."Three groups? 1) pdf 2) Online help
Who else?
The PDF files are produced by the documentation team, Online help is
what you find on the wiki help but also off line, maintained by
developers and l10n team. The third group is the Native Language
projects where documentation, marqueting, websites, QA etc are
translated and documented.
If you would like to work on the documentation, there is a huge need for
the off line help, several functionalities are not documented at all and
could be lost for the users.
The users guide are done by the documentation team, you just need to
jump on the list and ask for an account on the ODFAuthors site, and
follow the workflow there. Let me know if you have other questions.
Kind regards
Sophie
Hi David,
1) Yes, I have used the pdf documentation from time to time, but don't often have need to. Normally, only if I have a problem, which might occur when I'm trying something new and unfamiliar; but most of the time I am just using LO for the old and familiar! My first action in such a case would be to check the menus; if I can't find what I need there, I try searching more widely. It's not always easy to find what I want in a large document, though; but it's definitely comforting to know it's there, in case, and it has at times been useful.
2) I might think of doing this -- BUT: I use LO mainly on a machine without internet connection, having downloaded elsewhere and ported on a memory stick or similar. I believe that the help needs to be downloaded separately from the application, and I don't always remember to download the help along with the application, so this method doesn't always work for me!
3) Some thoughts. The documents are long; there must be a way to rapidly identify and get to the appropriate section. If there are too many large graphics, it makes scrolling through the document an arduous process; graphics should be used only where they really clarify something in the text, and should not be larger than necessary to achieve such clarification. Ease of use should always trump prettiness. This is a comment about documentation in general; the above comments may already be addressed in LO doc, it's a long time since I've looked, and my memory's not too great!
4) Probably already answered in (3); if I think of anything to add, I'll reply again.
best,/Gary
Hi 
I was really impressed to see the initial request for feedback *. Also
with the responses.
Even more feedback might be generated through the social media channels.
Has anyone here got any good ideas of a good way of asking the question(s)
in so few characters?
The Documentation Team and the people working on the 'inbuilt' help and the
International Translators ARE all 'normal users' - or at least that is
usually how they were when they first started contributing their time and
skills to LibreOffice/OpenOffice. Some work in more than one team and/or
move around between different teams but there is no formal "liaison" except
the generic "Projects" or "Discussion" mailing list.
The strongest informal links seem to be between the International
Translators and the 'in-built' help teams. As a result it seems that the
'in-built' help is fantastic in all languages except English. The English
version might be a little geeky, or "too perfect" or something else that
native English Speakers might find irksome. Anyway the main point is that
it translates VERY well - so, many thanks to all involved!! :)))
The Documentation Team was blessed with an extremely good team-leader who
poured tons of work into the project for many years (and still can't quite
stop herself from helping at all levels (luckily!!)). If there were a
medal for exceptionally good work and/or over a long time period then Jean
Weber deserves at least 10 of them. However there are other people in the
Documentation Team, now and in the past, who have varying amounts of
experience and/or skill. Sometimes it helps to have someone new and with
no skill or experience to proof-read to see how a 'normal' user might view
it or to see what a fresh pair of eyes sees. Sadly such people often learn
very quickly so a constant influx of 'noobs' might help!
* One problem that many community-led organisations have is the feeling
that asking other users how they feel or what they think is unnecessary
because everyone is free to jump in on any team's work at any time. Teams
such as Documentation often require a higher level of commitment and often
require some knowledge or understanding in order to be able to contribute.
Also there is far tooo much being done in far too many areas for almost
anyone to be able to spend enough time figuring out what all the different
teams are doing at any given moment.
So i think an occasional open-ended poll of 'normal' users (incl those from
other parts of the project) is truly excellent.
Many, many thanks to everyone who has already responded, or already been
involved or even is just lurking here.
Regards from
Tom
Hi
Oh, and to answer the questions that were asked!
I do use the Pdfs from the "Published Guides" pages. The main advantage is
that the index and chapter headings and such are all "clickable" to get me
to the correct topic very quickly.
I take Anne-ology's point about them being troublesome to add notes to (or
to copy chunks from) but the Pdfs are also in Odt format.
So i use whichever format seems best for what i need, or whichever one i
happen to "have most readily to hand" at a given moment. So that is a bit
random.
I rarely use the in-built help but when i have it has usually been
excellent. I am a bit of an aspie so maybe that helped - or maybe it is
just that the 'in-built' help is just excellent anyway. I've never had a
problem with the 'in-built' help, except that sometimes i need more detail
and hand-holding to help me through something i really didn't understand -
so i went to the Published Guides or googled-it (err, or duck-duckj-go'd
it) to get the extra bit i needed.
Yes i appreciate that most normal users don't know simple computer usage
that has been around 'forever'. I tend to click on the blue-circled
question mark rather than use F1. If the 'in-built' help is not installed
locally then it usually takes me to it's on-line pages. I don't think i
have had problems with any of that but i might not have noticed if it was
just a typical "computers don't always behave" type problem.
I am not sure what sort of format would be better. I like it the way it
is. If it changed i might grumble at first but then soon find i prefer the
new way.
I do like the video tutorials at "Spoken Tutorials";
http://spoken-tutorial.org/
I wish that other languages could take their structure and extend it into
other languages. Other video channels all seem to be less well-organised
or more dependent on a single person or unsustainably tiny team. However
it is nice to see a wealth of stuff out there and some interesting topics.
Regards from
Tom
Hi,
PDF? I'm not sure I know where to look for LO documentation in this format?
F1? I use it often. It needs to be compartmenalized (Calc, Writer, Math, Macro interface [UNO], ...) Its installation also needs to be better integrated into the LO installation process.
HTML? I occasionally wander into this maze though I'm not sure how I get there. I guess it's via a link someone posts on this list.
I'm a Calc user on Windows and on Linux. I use the Function Wizard to find function names by category and F1 to get the specifics as to the meaning of the function parameters. The examples are not always very well thought out in terms of being very practical.
I would write and use macros a good bit more if there were good documentation on the subject through F1. I'd like to see links to an on line tutorial on Star Basic and one or more tutorials on the concepts of UNO and how to get started using it. At least one tutorial should NOT assume that the reader has a degree in computer programming. I, for one, am a retired 1960s era assembler language and FORTRAN (later K&R C and Pascal) mainframe programner. My paradigm involves procedural code (get values, manipulate them, store/use the results, etc.). I need a bridge from that to the UNO paradigm.