simplifying documentation

classic Classic list List threaded Threaded
26 messages Options
12 « Prev
catdance catdance
Reply | Threaded
Open this post in threaded view
|

Re: simplifying documentation

There have been several posts about this issue but I am still not clear
how to suggest changes to the user interface. Exactly what should I do?


On 7/29/2017 5:46 AM, Olivier Hallot wrote:

> 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.
>
> Em 28/07/2017 23:27, Cathy Crumbley escreveu:
>>
>> 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?


--
To unsubscribe e-mail to: [hidden email]
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
catdance catdance
Reply | Threaded
Open this post in threaded view
|

Re: simplifying documentation

In reply to this post by DaveB
Dave,

Here is a suggestion that might help those of us who are new: a chart or
listing that attempts to show who is involved in the documentation team
and what they are doing.  It might be hard to ensure that everyone is
included but perhaps it could start with the people who have been
actively participating in the mailing list.  There is little hierarchy
but some people have higher levels of formal responsibility and it would
be good to know who they are.  If possible, it would be interesting to
know people's geographical locations as well.

A chart or listing for the overall LibreOffice structure would also be
helpful. It need not be very detailed but could give a sense of how it
is organized and maybe who some of the main players are.

It should be possible to produce these without significant effort. Or
better still, they already exist and just need to be linked to.

Cheers,

Cathy

On 7/29/2017 4:06 AM, Dave wrote:

> 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.
>
>
> On 29.07.2017 02:14, Cathy Crumbley wrote:
>> 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.
>>
>> On 7/28/2017 4:41 AM, Sophie wrote:
>>> Hi Cathy,
>>> Le 27/07/2017 à 21:55, Cathy Crumbley a écrit :
>>>> 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 :)
>>> Cheers
>>> Sophie


--
To unsubscribe e-mail to: [hidden email]
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
Ilmari Lauhakangas Ilmari Lauhakangas
Reply | Threaded
Open this post in threaded view
|

Re: simplifying documentation

In reply to this post by catdance
The process would be as follows for issues needing input from the design
team:

1. Register an account in Bugzilla:
https://bugs.documentfoundation.org/createaccount.cgi It requires an
email confirmation.
2. Start the creation of a new report:
https://bugs.documentfoundation.org/enter_bug.cgi?product=LibreOffice
3. Click Show advanced fields.
4. If it is about the general interface, change component to UI. If it
is about some specific feature, pick an application (Writer, Calc..).
5. If the issue is more of an innovative improvement rather than a fix
for something that broke, change Severity to enhancement.
6. In the Summary field, give a brief description of the matter.
7. In the description field you can describe it in more detail.
8. In the CC field, insert [hidden email]
9. In the keywords field near the bottom, insert needsUXEval

Optionally, you can include a screenshot with the Add an attachment
button. This is only needed for those cases when a picture tells more
than a thousand words.

Reporting something concerning the website(s), Redmine is the
appropriate tool:
https://redmine.documentfoundation.org/projects/infrastructure

On 05.08.2017 06:55, Cathy Crumbley wrote:

> There have been several posts about this issue but I am still not
> clear how to suggest changes to the user interface. Exactly what
> should I do?
>
>
> On 7/29/2017 5:46 AM, Olivier Hallot wrote:
>> 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.
>>
>> Em 28/07/2017 23:27, Cathy Crumbley escreveu:
>>>
>>> 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?

--
To unsubscribe e-mail to: [hidden email]
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

DaveB DaveB
Reply | Threaded
Open this post in threaded view
|

Re: simplifying documentation

In reply to this post by catdance
The LibreOffice project two main web facing aspects, the website
https://www.libreoffice.org/ and the wiki
https://wiki.documentfoundation.org/Main_Page
I think you already have wiki access, in which case you can make the
changes yourself, preferably after notifying the team (eg. the
documentation team's wiki) about those changes.
For the website there are a few different channels open for you to
submit your suggestions. Two that you might consider are:

  * Bugzilla (https://bugs.documentfoundation.org/ not an easy maze to
    navigate) which, in addition to bug reporting, is the central
    facility for anyone to request/suggest things like, core software
    code changes by the developer team, software user interface by the
    design team.
    Bugzilla submissions are categorized into areas of the project to
    which they relate. The "needsUXEval" Cor mentioned is a flag/marker
    which can be added to bring the submission to the attention of the
    design/user_experience team.

  * Post to the website mailing list [hidden email],
    with specific details of your suggestion. Note: The website team is
    often referred to as "Infra" (abbreviation of Infrastructure) See
    https://wiki.documentfoundation.org/Category:Infrastructure for more
    info.

The post from Ilmari Lauhakangas reached the list while I was typing
this and gives much more detailed step-by-step information.

Regards

Dave


On 05.08.2017 05:55, Cathy Crumbley wrote:

> There have been several posts about this issue but I am still not
> clear how to suggest changes to the user interface. Exactly what
> should I do?
>
>
> On 7/29/2017 5:46 AM, Olivier Hallot wrote:
>> 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.
>>
>> Em 28/07/2017 23:27, Cathy Crumbley escreveu:
>>>
>>> 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?
>
>

--
Please address any reply to the mailing list only. Any messages sent to
this noreply@ address are automatically deleted from the server and will
never be read.

--
To unsubscribe e-mail to: [hidden email]
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
DaveB DaveB
Reply | Threaded
Open this post in threaded view
|

Re: simplifying documentation

In reply to this post by catdance
Hi Cathy,

My responses are given in-line with your original message.

On 05.08.2017 06:24, Cathy Crumbley wrote:
> Dave,
>
> Here is a suggestion that might help those of us who are new: a chart
> or listing that attempts to show who is involved in the documentation
> team and what they are doing.

While I understand the "nice to have" proposal you are suggesting, I
think you might be misinterpreting the word "Team". We use the term to
describe those folks who are currently contributing to the project in
whatever area they have chosen. In open source projects contributors
come and go, some contribute intermittently over the long term, others
might make substantial contribution on a one-off basis. There are people
with interests in other areas of the project, who strictly speaking are
not part of the documentation "Team", but provide valuable assistance in
other ways. Keeping track and maintaining the chart/list you suggest
would be a task I would be unwilling to take on, or that all those
people who could be listed would wish to be included. The best that I
can suggest is to look through the "Contributors" and "Acknowledgments"
tables in the front pages of all documentation publications.

> It might be hard to ensure that everyone is included but perhaps it
> could start with the people who have been actively participating in
> the mailing list.

Only list moderators have access to the confidential list of subscriber
details. Posting to a mailing list is no indication of a person's actual
"Team" activity or involvement. Many people post, but only a few contribute.

> There is little hierarchy

No, there is no hierarchy, only levels of experience and willingness to
contribute.

> but some people have higher levels of formal responsibility and it
> would be good to know who they are.

The only people who have formal responsibilities are TDF (The Document
Foundation) board, elected by TDF members and a couple of sub-committees.
See the "Foundation" and "Governance" menu entries
http://www.documentfoundation.org/ for more information.
TDF board oversees the general management of the LibreOffice and
Document Liberation projects. TDF has appointed a small number of
contractors to assist in moving some areas of the LibreOffice project
forward, note that I said "assist", not control. Oliver is a TDF
founding member, a long time supporter of this software's development
since the time when it was first open sourced under the name
OpenOffice.org and has taken on the responsibility of assisting those of
us who wish to contribute to the documentation. Beyond that, all
contributors are equal. In this respect the only difference between you
and I is that I have long term experience with the software and although
not always an active contributor I have followed the documentation
development from it's beginning, but just like you, I had to research
and ask questions to understand how things worked when I first took an
interest in the software and project.

> If possible, it would be interesting to know people's geographical
> locations as well.

Unless contributors chose to volunteer that information, I don't know
how we could establish that. FWIW. I was born (hatched?) in West London,
near Heathrow airport and now live in Northern Italy. Oliver tells me he
is of French extraction and now lives in Brazil. I think Paul recently
mentioned that he is Canadian. In a previous post Jean Weber said she is
in the northern part of Queensland, Australia and Hazel is in the UK
(she thinks). In his introductory post Jorge mentioned Costa Rica. My
best guess is that you are somewhere in North America. Likewise, I could
only guess at the location of any other volunteers.

I recall seeing at least one other open source project's website that
had a world map pinned with the location of it's contributors?
committers? or similar. If you believe something like this would serve
to create more of a "team spirit", put out a call on this list for
contributors to provide the information and put it on the documentation
wiki.

> A chart or listing for the overall LibreOffice structure would also be
> helpful. It need not be very detailed but could give a sense of how it
> is organized and maybe who some of the main players are.

In terms of formal structure I can only refer you back to TDF web page menu.

For LibreOffice project main areas of activity see the list under the
heading "Teams": https://wiki.documentfoundation.org/Main_Page

For the organisation of the documentation development, please put
forward specific recommendations/suggestions for the changes/additions
you want to make to
https://wiki.documentfoundation.org/Documentation/Development if there
are no objections made within a reasonable period of time (we are all
subject to peer review), you are free to go ahead and make those
changes, or find someone willing to make them for you.

Not sure what you mean by "main players", because in my mind that
creates an idea of an organization structured like a corporation, rather
than volunteer driven project. If you mean the people widely recognized
as being most active within the project, I am not sure how those people
could be identified, with a few exceptions, an individual's level of
activity often changes. Then there are those people who are very active
and make vast contributions the project's success and progress with
their work outside of it's normal (formal?) structure. Not forgetting
the work of the folks in the Ask LibreOffice forum and other similarly
associated sections of the project.

I believe that Jean Weber (the former team lead) would qualify as the
longest serving, still active contributor to the documentation.

> It should be possible to produce these without significant effort.

On the contrary, much of what you are asking for would take considerable
effort and demand even more of mine, or someone else's already very
limited spare time.

> Or better still, they already exist and just need to be linked to.

Other than the links I have given above I am not aware of other links
that may serve your purpose. However, if you or anyone else finds
something that could be usefully linked, I would be happy make the linkages.

> Cheers,
>
> Cathy

Sorry if I appear negative, which I am definitely not trying to be, but
I am having difficulty in getting a handle on your perspective of how an
open source project functions. By it's very nature, being supported
(operated?) mainly by individuals from many countries, speaking
different languages, from a wide variety of cultures and each of those
individuals contributing to any area of a project in which they have an
interest, knowledge or experience, open source volunteer projects cannot
be neatly compartmentalized and structured. Some open source projects
are sponsored by corporations who exercise a measure of
management/control over those projects and may have a more formal
structure. In part TDF/LibreOffice came into being in order to break
away from such corporate management.

Cheers,
Dave

>
> On 7/29/2017 4:06 AM, Dave wrote:
>> 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.
>>
>>
>> On 29.07.2017 02:14, Cathy Crumbley wrote:
>>> 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.
>>>
>>> On 7/28/2017 4:41 AM, Sophie wrote:
>>>> Hi Cathy,
>>>> Le 27/07/2017 à 21:55, Cathy Crumbley a écrit :
>>>>> 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 :)
>>>> Cheers
>>>> Sophie



--
Please address any reply to the mailing list only. Any messages sent to
this noreply@ address are automatically deleted from the server and will
never be read.

--
To unsubscribe e-mail to: [hidden email]
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
DaveB DaveB
Reply | Threaded
Open this post in threaded view
|

Re: simplifying documentation

In reply to this post by sophi
Hi Sophie,

On 29.07.2017 19:08, Sophie wrote:

> Hi Dave,
> Le 29/07/2017 à 10:06, Dave a écrit :
>> 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.

Yes, I understand that, because I have first hand experience of this
situation with other software installations in commercial & government
locations. I deliberately omitted the point in order not to over
complicate my answer to the question.

>  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.

I understand that NLPs are free to translate as they see fit, but as you
and I know some NLPs like to keep the appearance and context of their
their websites in close alignment (not an exact translated copy) with
the default (English) website. I used the wrong terminology in saying
"everything has to be translated" when I should have said "the content
might have to be translated". Again, I was trying not to over complicate
my answer to the question.

> 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 :) thanks for the clarifications
> Cheers
> Sophie
I try to help out where I think it might be useful ;)
Cheers,
Dave
--
Please address any reply to the mailing list only. Any messages sent to
this noreply@ address are automatically deleted from the server and will
never be read.


--
To unsubscribe e-mail to: [hidden email]
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
12 « Prev