Tracking documentation content gap

classic Classic list List threaded Threaded
8 messages Options
Olivier Hallot-4 Olivier Hallot-4
Reply | Threaded
Open this post in threaded view
|

Tracking documentation content gap

Hi

I visited several documentation pages in the wiki and I have a question.

Assuming I am a skilled LO writer user, if I have to start producing
content, where do I look to start? What are the missing contents in the
guides vis-a-vis of the developments of the latest LO versions?

Please let me know if there is a wiki page for that purpose because the
one I saw is refers to easy-hacks and is outdated, poorly highlighted.

If help is welcome here, does it make sense to the documentation
comunity to have a metabug in bugzilla to track the missing
documentation contents? [1]. An update of the easy hack wikipage shall
suffice? Or a specific wiki page for that purpose is prefered?

Please advise.

[1] metabug for helpcontent missing/outdated pages:
https://goo.gl/ixqz7N

--
Olivier Hallot
Comunidade LibreOffice
http://ask.libreoffice.org/pt-br

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

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

Re: Tracking documentation content gap

Am 15.03.2016 um 21:08 schrieb Olivier Hallot:
> Hi
>
> I visited several documentation pages in the wiki and I have a question.
>
> Assuming I am a skilled LO writer user, if I have to start producing
> content, where do I look to start? What are the missing contents in the
> guides vis-a-vis of the developments of the latest LO versions?

Am I understanding you right: you are searching for a list of missing
content in the User Guides?

Why not starting from the original Release Notes pages?[1]

Or do you think that Release Notes are written too freaky for most of the
authors (who are bare users mostly)?

Regards, Nino

[1] https://wiki.documentfoundation.org/Category:ReleaseNotes



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

Martin Srebotnjak Martin Srebotnjak
Reply | Threaded
Open this post in threaded view
|

Re: Tracking documentation content gap

In reply to this post by Olivier Hallot-4
Hi,

if you are asking about the guides, the guides were updated to the latest
release versions as seen on the publications wiki, i.e. Getting Started
Guide was recently released for 5.0. It needs updating to 5.1. All the
work-in-progress can be tracked on the odfauthors.org site. Dedicated
module guides were mostly released for the 4.x series so they might not be
so much up-to-date.

IMHO GS is the most important guide as it is the entry level guide and it
is mostly required by any public administration or large deployment where
LO wants to be present - it is the proof that documentation exists and is
up-to-date. And of all the guides this one is the one that l10n teams do
and probably should devote most resources to localize (if they do not have
resources to localize all).

The GS guides do not cover all aspects of LO, and they are not intended to.
For that there are special guides for modules. So the GS guide is updated
and checked for errors with every update and I believe that Jean and her
team did a good work (as much as I could see from localizing the updated
strings), so I guess there are no known errors nor are there really missing
topics in GS50. It just needs to be updated to the latest release(s).

With 5.1 (and upcoming 5.2) there was/is a lot of menu restructuring going
on in LO so the updaters will have a lot of work with updating the menu
paths and with updating the screenshots (where menus are present), so the
5.1 update of GS guide will not be so much in adding content but in getting
it true to all the changes. And with all those menu changes LO really does
not have a truly up-to-date general or module-specific guide (LibreOffice
Base Handbook might be the only exemption, because there were no radical
changes in Base).

So I guess it would help to set priorities and the teams that will work on
those priorities. And we, the l10n teams will have something to localize
again ...

Lp, m.

2016-03-15 21:08 GMT+01:00 Olivier Hallot <[hidden email]>:

> Hi
>
> I visited several documentation pages in the wiki and I have a question.
>
> Assuming I am a skilled LO writer user, if I have to start producing
> content, where do I look to start? What are the missing contents in the
> guides vis-a-vis of the developments of the latest LO versions?
>
> Please let me know if there is a wiki page for that purpose because the
> one I saw is refers to easy-hacks and is outdated, poorly highlighted.
>
> If help is welcome here, does it make sense to the documentation
> comunity to have a metabug in bugzilla to track the missing
> documentation contents? [1]. An update of the easy hack wikipage shall
> suffice? Or a specific wiki page for that purpose is prefered?
>
> Please advise.
>
> [1] metabug for helpcontent missing/outdated pages:
> https://goo.gl/ixqz7N
>
> --
> Olivier Hallot
> Comunidade LibreOffice
> http://ask.libreoffice.org/pt-br
>
> --
> 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
>
>

--
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
sophi sophi
Reply | Threaded
Open this post in threaded view
|

Re: Tracking documentation content gap

In reply to this post by Olivier Hallot-4
Hi Olivier,
Le 15/03/2016 21:08, Olivier Hallot a écrit :
> Hi
>
> I visited several documentation pages in the wiki and I have a question.
>
> Assuming I am a skilled LO writer user, if I have to start producing
> content, where do I look to start?

This is not clear to me if you are speaking about contributing
documentation, or producing own content using advanced functions

 What are the missing contents in the
> guides vis-a-vis of the developments of the latest LO versions?

As Martin said, mostly updates on the per module guides
>
> Please let me know if there is a wiki page for that purpose because the
> one I saw is refers to easy-hacks and is outdated, poorly highlighted.

The wiki needs to be structured since a long time :). I think the "Help
produce documentation" part should be divided in User guides/Wiki
content/Help content/Videos/etc. and guide contributions from dedicated
pages
>
> If help is welcome here, does it make sense to the documentation
> comunity to have a metabug in bugzilla to track the missing
> documentation contents? [1]. An update of the easy hack wikipage shall
> suffice? Or a specific wiki page for that purpose is prefered?

I'm not sure people here would be at ease with BugZilla which is far
from being user friendly, I find Redmine easier than BZ and the wiki
easier than both.
What does others think?

Cheers
Sophie

--
Sophie Gautier [hidden email]
GSM: +33683901545
IRC: sophi
Co-founder - Release coordinator
The Document Foundation

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

Olivier Hallot-4 Olivier Hallot-4
Reply | Threaded
Open this post in threaded view
|

Re: Tracking documentation content gap

Hi Sophie

Em 16/03/2016 10:41, Sophie escreveu:

> Hi Olivier,
> Le 15/03/2016 21:08, Olivier Hallot a écrit :
>> Hi
>>
>> I visited several documentation pages in the wiki and I have a question.
>>
>> Assuming I am a skilled LO writer user, if I have to start producing
>> content, where do I look to start?
>
> This is not clear to me if you are speaking about contributing
> documentation, or producing own content using advanced functions

It is the missing contents. The job in documenting is twofold: 1) update
existing books with the changes in the applications, and 2) write about
the new features. It is slightly diferent.

Do you all agree?


>
>  What are the missing contents in the
>> guides vis-a-vis of the developments of the latest LO versions?
>
> As Martin said, mostly updates on the per module guides
>>
>> Please let me know if there is a wiki page for that purpose because the
>> one I saw is refers to easy-hacks and is outdated, poorly highlighted.
>
> The wiki needs to be structured since a long time :). I think the "Help
> produce documentation" part should be divided in User guides/Wiki
> content/Help content/Videos/etc. and guide contributions from dedicated
> pages

Agree. It is quite time consuming to get the full picture.

>>
>> If help is welcome here, does it make sense to the documentation
>> comunity to have a metabug in bugzilla to track the missing
>> documentation contents? [1]. An update of the easy hack wikipage shall
>> suffice? Or a specific wiki page for that purpose is prefered?
>
> I'm not sure people here would be at ease with BugZilla which is far
> from being user friendly, I find Redmine easier than BZ and the wiki
> easier than both.

I am ok with a wiki page. As I answered Martin, I'll produce a wiki page
that can let us track features x versions for the 5.x family and beyond.


> What does others think?
>
> Cheers
> Sophie
>

--
Olivier Hallot
Comunidade LibreOffice
http://ask.libreoffice.org/pt-br

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

Olivier Hallot-4 Olivier Hallot-4
Reply | Threaded
Open this post in threaded view
|

Re: Tracking documentation content gap

In reply to this post by Martin Srebotnjak
Hello Martin
Thanks for aswering.

Em 16/03/2016 07:58, Martin Srebotnjak escreveu:
> Hi,
>
> if you are asking about the guides, the guides were updated to the latest
> release versions as seen on the publications wiki, i.e. Getting Started
> Guide was recently released for 5.0. It needs updating to 5.1. All the
> work-in-progress can be tracked on the odfauthors.org site. Dedicated
> module guides were mostly released for the 4.x series so they might not be
> so much up-to-date.

I'm glad to get your summary.

>
> IMHO GS is the most important guide as it is the entry level guide and it
> is mostly required by any public administration or large deployment where
> LO wants to be present - it is the proof that documentation exists and is
> up-to-date. And of all the guides this one is the one that l10n teams do
> and probably should devote most resources to localize (if they do not have
> resources to localize all).

Indeed. There seems to be a concensus that the english GS is the base
for translations.

>
> The GS guides do not cover all aspects of LO, and they are not intended to.

Agree.


> For that there are special guides for modules. So the GS guide is updated
> and checked for errors with every update and I believe that Jean and her
> team did a good work (as much as I could see from localizing the updated
> strings), so I guess there are no known errors nor are there really missing
> topics in GS50. It just needs to be updated to the latest release(s).

And thus my question: what are the topics introduced in the software
that needs documentation writing? If there is a list somewhere, then
fine, and I'd like to see it. If there is'nt, then ok I'll try to write
one.

>
> With 5.1 (and upcoming 5.2) there was/is a lot of menu restructuring going
> on in LO so the updaters will have a lot of work with updating the menu
> paths and with updating the screenshots (where menus are present), so the
> 5.1 update of GS guide will not be so much in adding content but in getting
> it true to all the changes. And with all those menu changes LO really does
> not have a truly up-to-date general or module-specific guide (LibreOffice
> Base Handbook might be the only exemption, because there were no radical
> changes in Base).

Indeed

>
> So I guess it would help to set priorities and the teams that will work on
> those priorities. And we, the l10n teams will have something to localize
> again ...

There is a wikipage that shows the tasklist for the Guides[1].

I see that the GS guides are quite updated and have been carried well
given the resource limitations.

The modules guides concerns me because they are lagging behind
LibreOffice development.

For these modules guides I plan to write a wiki page with the topics x
version that are missing. That way we will have a roadmap on producing
contents, that will come along the update of the existing guides.

If there are objections to this initiative, please let me know (It may
be a very large job to carry).

[1]
https://wiki.documentfoundation.org/Documentation/Development/UserGuideTasks

>
> Lp, m.
>
> 2016-03-15 21:08 GMT+01:00 Olivier Hallot <[hidden email]>:
>
>> Hi
>>
>> I visited several documentation pages in the wiki and I have a question.
>>
>> Assuming I am a skilled LO writer user, if I have to start producing
>> content, where do I look to start? What are the missing contents in the
>> guides vis-a-vis of the developments of the latest LO versions?
>>
>> Please let me know if there is a wiki page for that purpose because the
>> one I saw is refers to easy-hacks and is outdated, poorly highlighted.
>>
>> If help is welcome here, does it make sense to the documentation
>> comunity to have a metabug in bugzilla to track the missing
>> documentation contents? [1]. An update of the easy hack wikipage shall
>> suffice? Or a specific wiki page for that purpose is prefered?
>>
>> Please advise.
>>
>> [1] metabug for helpcontent missing/outdated pages:
>> https://goo.gl/ixqz7N
>>
>> --
>> Olivier Hallot
>> Comunidade LibreOffice
>> http://ask.libreoffice.org/pt-br
>>
>> --
>> 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
>>
>>
>

--
Olivier Hallot
Comunidade LibreOffice
http://ask.libreoffice.org/pt-br

--
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
Jean Weber Jean Weber
Reply | Threaded
Open this post in threaded view
|

Re: Tracking documentation content gap

On Thu, Mar 17, 2016 at 1:41 PM, Olivier Hallot
<[hidden email]> wrote:

> Hello Martin
> Thanks for aswering.
>
> Em 16/03/2016 07:58, Martin Srebotnjak escreveu:
>> Hi,
>>
>> if you are asking about the guides, the guides were updated to the latest
>> release versions as seen on the publications wiki, i.e. Getting Started
>> Guide was recently released for 5.0. It needs updating to 5.1. All the
>> work-in-progress can be tracked on the odfauthors.org site. Dedicated
>> module guides were mostly released for the 4.x series so they might not be
>> so much up-to-date.
>
> I'm glad to get your summary.
>
>>
>> IMHO GS is the most important guide as it is the entry level guide and it
>> is mostly required by any public administration or large deployment where
>> LO wants to be present - it is the proof that documentation exists and is
>> up-to-date. And of all the guides this one is the one that l10n teams do
>> and probably should devote most resources to localize (if they do not have
>> resources to localize all).
>
> Indeed. There seems to be a concensus that the english GS is the base
> for translations.
>
>>
>> The GS guides do not cover all aspects of LO, and they are not intended to.
>
> Agree.
>
>
>> For that there are special guides for modules. So the GS guide is updated
>> and checked for errors with every update and I believe that Jean and her
>> team did a good work (as much as I could see from localizing the updated
>> strings), so I guess there are no known errors nor are there really missing
>> topics in GS50. It just needs to be updated to the latest release(s).
>
> And thus my question: what are the topics introduced in the software
> that needs documentation writing? If there is a list somewhere, then
> fine, and I'd like to see it. If there is'nt, then ok I'll try to write
> one.
>
>>
>> With 5.1 (and upcoming 5.2) there was/is a lot of menu restructuring going
>> on in LO so the updaters will have a lot of work with updating the menu
>> paths and with updating the screenshots (where menus are present), so the
>> 5.1 update of GS guide will not be so much in adding content but in getting
>> it true to all the changes. And with all those menu changes LO really does
>> not have a truly up-to-date general or module-specific guide (LibreOffice
>> Base Handbook might be the only exemption, because there were no radical
>> changes in Base).
>
> Indeed
>
>>
>> So I guess it would help to set priorities and the teams that will work on
>> those priorities. And we, the l10n teams will have something to localize
>> again ...
>
> There is a wikipage that shows the tasklist for the Guides[1].
>
> I see that the GS guides are quite updated and have been carried well
> given the resource limitations.
>
> The modules guides concerns me because they are lagging behind
> LibreOffice development.
>
> For these modules guides I plan to write a wiki page with the topics x
> version that are missing. That way we will have a roadmap on producing
> contents, that will come along the update of the existing guides.
>
> If there are objections to this initiative, please let me know (It may
> be a very large job to carry).
>
> [1]
> https://wiki.documentfoundation.org/Documentation/Development/UserGuideTasks
>>

I have found that the most time consuming thing is to check what has
changed in LO and therefore needs updating in the books, even more
than what is missing because it is new in LO. I have to look at the
program and compare it to the book, testing the procedures as I go, in
order to find many topics that need updating. Sometimes the images
need to be changed, even if the text is still correct. With new
topics, one must decide where they should go: in which chapter and
where in that chapter. Sometimes this is easy to decide, but many
times it is not. Writing about new features often requires changing
text in other places as well (for example, the change to the sidebar
has meant a lot of rewriting on where to find tools in topics about
using those tools).

So a list of topics is a good and important thing to do, but will
probably not be enough unless it is very detailed. But I'm sure you
know all this.

--Jean

--
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
Jean Weber Jean Weber
Reply | Threaded
Open this post in threaded view
|

Re: Tracking documentation content gap

On Thu, Mar 17, 2016 at 3:01 PM, Jean Weber <[hidden email]> wrote:

> On Thu, Mar 17, 2016 at 1:41 PM, Olivier Hallot
> <[hidden email]> wrote:
>> Hello Martin
>> Thanks for aswering.
>>
>> Em 16/03/2016 07:58, Martin Srebotnjak escreveu:
>>> Hi,
>>>
>>> if you are asking about the guides, the guides were updated to the latest
>>> release versions as seen on the publications wiki, i.e. Getting Started
>>> Guide was recently released for 5.0. It needs updating to 5.1. All the
>>> work-in-progress can be tracked on the odfauthors.org site. Dedicated
>>> module guides were mostly released for the 4.x series so they might not be
>>> so much up-to-date.
>>
>> I'm glad to get your summary.
>>
>>>
>>> IMHO GS is the most important guide as it is the entry level guide and it
>>> is mostly required by any public administration or large deployment where
>>> LO wants to be present - it is the proof that documentation exists and is
>>> up-to-date. And of all the guides this one is the one that l10n teams do
>>> and probably should devote most resources to localize (if they do not have
>>> resources to localize all).
>>
>> Indeed. There seems to be a concensus that the english GS is the base
>> for translations.
>>
>>>
>>> The GS guides do not cover all aspects of LO, and they are not intended to.
>>
>> Agree.
>>
>>
>>> For that there are special guides for modules. So the GS guide is updated
>>> and checked for errors with every update and I believe that Jean and her
>>> team did a good work (as much as I could see from localizing the updated
>>> strings), so I guess there are no known errors nor are there really missing
>>> topics in GS50. It just needs to be updated to the latest release(s).
>>
>> And thus my question: what are the topics introduced in the software
>> that needs documentation writing? If there is a list somewhere, then
>> fine, and I'd like to see it. If there is'nt, then ok I'll try to write
>> one.
>>
>>>
>>> With 5.1 (and upcoming 5.2) there was/is a lot of menu restructuring going
>>> on in LO so the updaters will have a lot of work with updating the menu
>>> paths and with updating the screenshots (where menus are present), so the
>>> 5.1 update of GS guide will not be so much in adding content but in getting
>>> it true to all the changes. And with all those menu changes LO really does
>>> not have a truly up-to-date general or module-specific guide (LibreOffice
>>> Base Handbook might be the only exemption, because there were no radical
>>> changes in Base).
>>
>> Indeed
>>
>>>
>>> So I guess it would help to set priorities and the teams that will work on
>>> those priorities. And we, the l10n teams will have something to localize
>>> again ...
>>
>> There is a wikipage that shows the tasklist for the Guides[1].
>>
>> I see that the GS guides are quite updated and have been carried well
>> given the resource limitations.
>>
>> The modules guides concerns me because they are lagging behind
>> LibreOffice development.
>>
>> For these modules guides I plan to write a wiki page with the topics x
>> version that are missing. That way we will have a roadmap on producing
>> contents, that will come along the update of the existing guides.
>>
>> If there are objections to this initiative, please let me know (It may
>> be a very large job to carry).
>>
>> [1]
>> https://wiki.documentfoundation.org/Documentation/Development/UserGuideTasks
>>>
>
> I have found that the most time consuming thing is to check what has
> changed in LO and therefore needs updating in the books, even more
> than what is missing because it is new in LO. I have to look at the
> program and compare it to the book, testing the procedures as I go, in
> order to find many topics that need updating. Sometimes the images
> need to be changed, even if the text is still correct. With new
> topics, one must decide where they should go: in which chapter and
> where in that chapter. Sometimes this is easy to decide, but many
> times it is not. Writing about new features often requires changing
> text in other places as well (for example, the change to the sidebar
> has meant a lot of rewriting on where to find tools in topics about
> using those tools).
>
> So a list of topics is a good and important thing to do, but will
> probably not be enough unless it is very detailed. But I'm sure you
> know all this.
>
> --Jean


A note for writers: many topics in the updated Getting Started guide
can be reused in the module guides, with only small changes. Reuse is
faster than rewriting, requires less reviewing and editing, and helps
provide consistency among books. It's also a good way to discover that
sometimes the topic in GS is not quite correct or complete.

--Jean

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