simplifying documentation

Documentation General
#1

HI All,

I just uploaded a review of Chapter 2 of the Writer Guide and would like to share a couple of thoughts.

It can take many words to explain a relatively simple concept when wording in the program itself is unclear or even misleading. Is there a mechanism for giving feedback to the developers about changing some of the wording within the program? If so, how does that work?

What is the relationship between Help and the Guides? It sounds like they are on two separate tracks. Are they duplicating information independently?

Cathy

#2

Hi Cathy,

Thanks very much for working on this. I note that you have put your
files into the LO Authors 5.3 Writer Guide "Feedback" folder. Jean
Hollis-Weber put a fair amount of time and effort into drafting a number
of the chapters for what was to be the 5.3 Writer Guide, but since we
are now working on the 6.0 guides, it seems highly unlikely that the 5.3
edition will go to publication.

I have now created the "Draft" and "Feedback" folders for the 6.0 Writer
Guide. Could you please retract (delete) your chapters 1 & 2 files from
the 5.3 "Feedback" folder and put them into the 6.0 "Drafts" folder for
review.

As to raising the issue of unclear or even misleading wording in the
help files, my _*guess*_ would be, that for very specific entries in the
help files you could raise an issue on Bugzilla:
https://wiki.documentfoundation.org/QA/BugReport
or contact Oliver for assistance.

Always keep in mind the help file is intended more as an "aide memoire"
for users who have some measure of familiarity with the software, rather
than a detailed guide. Obviously, there will be some of the same content
in both, but since they serve a different purpose and a different kind
of readership they are not duplicating information. My personal opinion
is that the In-Built Help and Documentation should never become one and
the same. As a long term, relatively experienced, user of the software
there I times when I look to the help files for short simple pointers to
help me get something done. There are way too many software packages out
there that force me to dig through a mountain of irrelevant "guff" to
find those short simple pointers.

Traditionally the In-Built Help and Documentation were handled
separately. Comparatively recently the project management decided to
bring both under the umbrella of the documentation team. As I mentioned
in another post, Oliver has done a lot of work to make it easier for
people not familiar with the help system file structure to work on the
help system. For more information go to:
https://wiki.documentfoundation.org/Documentation
and look at the various "Help" related entries under the "HELP PRODUCE
documentation" section.

Best Regards
Dave

#3

Hi Cathy

What is the relationship between Help and the Guides? It sounds like
they are on two separate tracks. Are they duplicating information
independently?

I'm glad you raised this question.

Yes they are separated tracks and contents duplication is a fact, at
least partially. Help pages are instance of web on-line pages, and
guides are instances of printed books. Different form factors for
different usage.

The Help is part of the software and is invoked when you press F1 or
click on the Help button in a dialog.

Because it is part of the application, the following applies

* It is a flat and factual description of the feature, eventually with
examples and use cases. Its objective is to help users to get the job done.

* The Help pages are translated into all released languages (currently
68 languages).

* It must contain the most accurate information on the features of the
software.

* Is must be indexed for easy referencing and search.

However, not everything is actually true...

* Translation of the Help depends on volunteers, which have limited time
available for the task. This however does not prevent us from releasing
new versions, but with unfinished translations in some cases.

* A significant part of the Help is also a user guide, which overlaps
with the current Guides we have. However, editing Help pages and
inserting it into the Help system is way more complex than
writing/updating a text document in Writer, as we do for the guides. I'd
like to discuss the contents of the Help User Guide and see if the Help
system needs to get leaner.

* The help system is poorly illustrated, almost everything is textual
with very few images and no videos.

* Because of the way the software is developed, LibreOffice developers
don't write software specification paperwork, and new features mushrooms
in the code, with no documentation or help page associated (with rare
and much appreciated exceptions). Many new developments as well as
changes in the user interface are not documented yet in the Help, which
means the Help is lagging with respect to the software. We are however
collecting these gaps in a list and looking for volunteers to write about.

What prevents us to evolve with the Help, and find something more easy
for volunteers to contribute?

* we must absolutely preserve its current contents and translations
process, people don't like useless rework.

* We don't have a replacing technology that can in a finger snap, make
all the legacy content available to a more user-friendly editing
process. My last blog post addresses the issue.
https://goo.gl/j3DVAG

There will be a workshop in Rome, at our LibreOffice Conference where we
will discuss these issues and more. I hope to meet all authors involved.

http://conference.libreoffice.org/

Kind regards

#4

Hi Dave,

What you are saying about the upgrade makes sense. I will put the reviewed chapters in with the 6.0 guides.

It is helpful to know some of the background on the Help files. I will combine my response to you with my response to Olivier.

Unfortunately, my question was not clear. I was asking about names and descriptions in the program itself, not the Help files. As an example, "Load with user settings" is just not clear. Re-wording could specify if it is talking about the current user or the previous user. It might be a relatively simple fix or it might not be. I don't know. But if it is, it seems like a no-brainer that would make the program more user friendly.

Thanks again,

Cathy

#5

reorganising and rewriting it as well as updating to v5.3, I hope it will
be a useful starting point for v6.0 even if it's not published for a 5.x
version.

BTW, my name is not hyphenated. Hollis is my middle name; Weber is my
surname.

--Jean

#6

Hi Cathy,

It can take many words to explain a relatively simple concept when
wording in the program itself is unclear or even misleading. Is there a
mechanism for giving feedback to the developers about changing some of
the wording within the program? If so, how does that work?

As to raising the issue of unclear or even misleading wording in the
help files, my _*guess*_ would be, that for very specific entries in the
help files you could raise an issue on Bugzilla:
https://wiki.documentfoundation.org/QA/BugReport
or contact Oliver for assistance.

Indeed issues are the proper way to suggest better wording.
You may add needsUXEval to the keywords field, so that the UX team,
deciding on improvements, finds your proposal easily.

thanks for your help!
Cor

#7

Hi Olivier,

Thank you for the explanation. It is impressive to see that it is available (in part) in 68 languages.

I have been using LibreOffice since last September. In that time, I have barely used Help because it is so hard to find the information I am looking for. Since it seems to offer little value, I have been wondering why so much work has been going into developing it.

Then, I read below where you say "Because it is part of the application..." This made no sense since it is not part of the application but rather a website. This made me wonder if I was missing something.

So, I went to the download page and noticed that there is a file called "Help for offline use." It is possible that I saw this before but paid no attention because I am always online.

Finally, I downloaded the file and realized what I have been missing.

Perhaps I am a dunderhead but if I missed the Help files, perhaps others have. I would strongly recommend that the download page be clearer about what the file contains. Can this feedback be passed on to the appropriate people or should I submit it somewhere?

On another note, I have been wondering how to find information about the project as a whole. Then I looked at the blog post you linked to and found pages with some of the information I have been looking for. I would like to suggest that new members like me be referred to that site as an introduction to the LibreOffice project.

By the way, I noticed an archived tender (July 2016) to redesign the download page. Does anyone know if that means that it has already been redesigned and that it will not be changed for a while?

Thanks again.

Cathy

#8

Hello Cathy

Hi Olivier,

(snip)

Finally, I downloaded the file and realized what I have been missing.

Perhaps I am a dunderhead but if I missed the Help files, perhaps others
have. I would strongly recommend that the download page be clearer about
what the file contains. Can this feedback be passed on to the
appropriate people or should I submit it somewhere?

No dunderhead at all and thanks again for raising the issue. This is an
old issue and people keep bypassing the download of the Help. I know the
Help is not downloaded because it pulls a string in the forums and
mailing lists on very basic subjects, typical of those who do not access
a Help, for whatever reason.

On another note, I have been wondering how to find information about the
project as a whole. Then I looked at the blog post you linked to and
found pages with some of the information I have been looking for. I
would like to suggest that new members like me be referred to that site
as an introduction to the LibreOffice project.

We keep a wiki for that purpose. But it requires permanent reordering
and addition/deletion/update of hundreds of pages, permanently.

We also have our main website (www.libreoffice.org) with information on
the project.

By the way, I noticed an archived tender (July 2016) to redesign the
download page. Does anyone know if that means that it has already been
redesigned and that it will not be changed for a while?

The download page has been reworked recently.

Kind regards

#9

Hi Olivier,

Thanks again for the responses.

If this has been a problem for a while, I am puzzled about why it has not been fixed. Are you aware of a reason why the download page cannot be re-worded now?

To be clear, what are you saying is the best source of information for people who are new to this and want to learn about the overall LibreOffice project? Are you saying that the wiki is not useful because so much work needs to be done on it?

As long as I am asking questions, here is one more: What is the Pootle server?

Cheers,

Cathy

#10

Hi Cor,

Just to be clear, I was not expressing problems with the Help files. In fact, I was not even aware that they exist when I wrote this.

Thank you!

Cathy

#11

Hi Cathy,

Just to be clear, I was not expressing problems with the Help files. In
fact, I was not even aware that they exist when I wrote this.

In know that you was talking about the user interface. That is what my
comment is about too :wink:

#12

Hi Cathy,

Hi Olivier,

Thanks again for the responses.

If this has been a problem for a while, I am puzzled about why it has
not been fixed. Are you aware of a reason why the download page cannot
be re-worded now?

It depends on which download page you're talking about. The download
page on the main website is reworked by infrastructure, design and
marketing project, together with the donate page. It's currently being
improved before being translated. For the download page of the
documentation project, the page is quite new, and maybe no volunteer had
time to work on it for the moment.

To be clear, what are you saying is the best source of information for
people who are new to this and want to learn about the overall
LibreOffice project? Are you saying that the wiki is not useful because
so much work needs to be done on it?

On the wiki, you'll see the different sub-projects of the LibreOffice
overall project, mainly: development, QA (quality assurance), UX/Design
(user experience), l10n (localization), documentation, infrastructure,
marketing, certification and NLPs (native language projects). All those
sub projects interact together to finally deliver LibreOffice the
product. You'll find also information about the Document Liberation
Project (DLP) which is another project under TDF umbrealla.

As long as I am asking questions, here is one more: What is the Pootle
server?

Pootle is an instance used by the l10n team to localize LibreOffice UI
and Help, part of the website, LibreOffice On Line currently.

Don't hesitate to ask any question you have :slight_smile:
Cheers
Sophie

#13

Thanks for your input. These is much to learn!

I am referring to the LibreOffice download page. Why? Because it sounds like I am not the only one who is unaware that we need to download a separate file for the Help files. It should be a relatively simple fix to just re-word what is on that page so that people understand. It is puzzling that this has not been done since people are aware of the problem.

I can see what is on the wiki. However, Olivier said "But it requires permanent reordering and addition/deletion/update of hundreds of pages, permanently." I was trying to understand if he was saying that it is not a great source of information. In any case, it sounds like it is the only place to get an overview of LibreOffice (although it is still challenging to do so).

From your description of Pootle, I was able to learn that an online version of LibreOffice is in the works. I don't really understand the rest of it, but at least I now know that Pootle is related to that project.

#14

Hi Cor,

I appreciate your advice about how to get the wording revised on the program download page. Unfortunately, I don't know what adding "needsUXEval to the keywords field" means.

Could you please translate into plain English?

Thank you.

Cathy

#15

On the (US English) download page, inside the box for the chosen version
it reads:
<Q>
LibreOffice 5.4.0 release notes
Supplementary Downloads:
Help for offline use: English (US) (Torrent, Info)
need another language?
</Q>
The installer file for the off-line/local help facility, is offered as
"Supplementary" (additional) to the main installation file, because it
is a convenience option, not an essential requirement to use the
software. If the off-line help is not installed the software
automatically attempts to provide the on-line equivalent in the user's
web browser. If you have a suggestion for the "simple fix" rewording to
convey this in a few words, we can put it forward to the website team.
"Few words", because everything has to be translated into many
(https://www.libreoffice.org/community/nlc/) languages, by our
(overworked) translation volunteers.

Oliver was not suggesting the wiki is not a good source of information.
The wiki content has been built up over a number of years and in some
areas it would benefit from a bit of housekeeping. As with all things in
open source software, there is always much more work to be done than
there are hands to do it.

You seem to be looking for some kind of single reference source that
will inform people about everything within the complex structure of this
fairly large project. Can you give some indication as to what level of
detail and what audience(s) such a source should cater for. Maybe
something suitable could be drafted and put forward as an overview for
the "Get Involved" page:
https://www.libreoffice.org/community/get-involved/

You might have misinterpreted Sophie's post. Pootle is not exclusively
related to the online version of the software, it is a
tool/facility/service used by the translators for many aspects of the
software.

#16

Hello Cathy

needsUXEval is a buzzword for "Need User Experience Team evaluation". We
have a group of people specialized in software user interface design
that evaluates all aspects of the human interaction with the software.

#17

Hi Dave,

On the (US English) download page, inside the box for the chosen version
it reads:
<Q>
LibreOffice 5.4.0 release notes
Supplementary Downloads:
Help for offline use: English (US) (Torrent, Info)
need another language?
</Q>
The installer file for the off-line/local help facility, is offered as
"Supplementary" (additional) to the main installation file, because it
is a convenience option, not an essential requirement to use the
software.

In some countries it's a legal requirement to have the help files
alongside the software, that's why it's also available as a package, for
IT department to be able to install it together with the product.

If the off-line help is not installed the software

automatically attempts to provide the on-line equivalent in the user's
web browser. If you have a suggestion for the "simple fix" rewording to
convey this in a few words, we can put it forward to the website team.
"Few words", because everything has to be translated into many
(https://www.libreoffice.org/community/nlc/) languages, by our
(overworked) translation volunteers.

Yes, but to be exact, NLPs doesn't translate the exact content, it's up
to them to translate what they want and adapt it to their language.

Oliver was not suggesting the wiki is not a good source of information.
The wiki content has been built up over a number of years and in some
areas it would benefit from a bit of housekeeping. As with all things in
open source software, there is always much more work to be done than
there are hands to do it.

You seem to be looking for some kind of single reference source that
will inform people about everything within the complex structure of this
fairly large project. Can you give some indication as to what level of
detail and what audience(s) such a source should cater for. Maybe
something suitable could be drafted and put forward as an overview for
the "Get Involved" page:
https://www.libreoffice.org/community/get-involved/

You might have misinterpreted Sophie's post. Pootle is not exclusively
related to the online version of the software, it is a
tool/facility/service used by the translators for many aspects of the
software.

Yes :slight_smile: thanks for the clarifications
Cheers
Sophie

#18

Cor,
I don't see a keywords field when entering a bug in Bugzilla.
Are you perhaps referring to the Summary field? If not, what am I missing?

--Jean

#19

Ah, I found it. I had to click "Show Advanced Fields" fields first.
Then it's down near the bottom, below Add an Attachment.

--Jean

#20

Indeed - thanks for mentioning that detail Jean,

Greetings,
Cor

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