[SeasonOfDocs] GeoNetwork Docs meeting notes

[Cameron Shorter]

Thanks Swapnil,

Great first pass. I've added comments in the document. A few big 
comments, though many are small and picky. Some really should be pulled 
up into TheGoodDocsProject master template. (You are welcome to add 
suggestions into TheGoodDocsProject - but that is likely to be 
time-consuming - so for efficiency I suggest that we consider fixing 
TheGoodDocsProject as out-of-scope for SeasonOfDocs.

Maria, good point re Writing Style. There is quite a bit more to good 
style than gender neutral language. I'd suggest it be addressed by 
pointing to an existing Style Guide for reference.

In the GoodDocsProject we selected Google's Style Guide. 
https://developers.google.com/style

I think we can aspire to follow such a guide, but we can't expect all 
contributors to become experts in such a guide before writing - 
otherwise we'd get no docs at all.

Maybe add a sentence along the lines of:

"We aspire to align with Google's developer documentation style guide, 
but most of our documentation hasn't been reviewed against this guide, 
and we don't expect you to review your updates against this guide 
either. Complete and accurate docs are better than incomplete perfectly 
styled docs."

On 21/1/20 1:18 am, María Arias de Reyna wrote:
> Dear Swapnil,
>
> It looks simple and clean. It looks how our tutorials should be :)
>
> Any suggestions on the language or writing style? I always try to use
> gender neutral language[1] but I guess there must be more similar
> recommendations out there for writing tutorials? For example, being a
> technical documentation, I am not sure how useful would be something
> like a Readability test[2].
>
> [1] https://en.wikipedia.org/wiki/Gender-neutral_language
> [2]https://en.wikipedia.org/wiki/Flesch%E2%80%93Kincaid_readability_test
>
> On Mon, Jan 20, 2020 at 1:34 PM Swapnil Ogale <swapnilogale at gmail.com> wrote:
>> Thanks for the notes Cameron.
>>
>> As discussed, I've had a go at putting together some info for a How-To article: https://docs.google.com/document/d/1lSoAf9vDeuSvsF6snCDKsIvFpiSJV8_ouXs_ovrXWWA/edit?usp=sharing
>> (I've also added an example using the template in the same doc)
>>
>> Can you please review this and let me know what you think?
>>
>> Meanwhile, I'll keep working on updating Byron's spreadsheet on identifying the gaps.
>>
>> Cheers,
>> Swapnil
>>
>> On Thu, 16 Jan 2020 at 21:12, Cameron Shorter <cameron.shorter at gmail.com> wrote:
>>> Present: Swapnil Ogale, Jo Cook, Paul van Genuchten, Byron Cochrain,
>>> Maria Aras de Rayna
>>>
>>> Swapnil has reviewed Windows getting started documentation, and has
>>> worked out how to get it working. He will be submitting changes.
>>>
>>> In list of documents [1] Swapnil has categorised "Current Content Type"
>>> pages as per key doc types[2]. Next, Swapnil plans to categorise pages
>>> into "Ideal Document Types" and enable finding gaps.
>>>
>>> Maria noted that to date, most documentation has been developed by
>>> individuals without much collaboration. She thinks it valuable to
>>> provide a template which people can write against and collaborate around.
>>>
>>> Paul/Maria noted that there is an extensive translations of GeoNetwork
>>> docs. We considered limiting doc changes due to impact on translations.
>>> However, with Maria's blessing, we feel that it is best to have at least
>>> one excellent set of English docs, and it is then up to the translators
>>> to keep up.
>>>
>>> Jo suggested that we should suggest that translators wait for a set
>>> milestone and doc baseline before translating. Eg: wait until Swapnil
>>> finishes SeasonOfDocs stint. (Final week is 24 Feb 2020).
>>>
>>> If Paul is right about there being a healthy community of translators,
>>> some of these people might be able to help improve existing docs if we
>>> provide a suitable template to follow. Paul said he'd follow up on this.
>>>
>>> Swapnil volunteered to convert an existing doc to an exemplar doc, using
>>> TheGoodDocsProject [3] [4] as a guide (note that it is still alpha and
>>> might not fit well with GeoNework). Swapnil will focus on a Howto first,
>>> then move to a Tutorial.
>>>
>>> Once an exemplar is in place, Swapnil will invite others to review. I'll
>>> review, hope others will too.
>>>
>>> After the review, Paul and Maria offered to test writing against the
>>> exemplar / template. Byron is interested in writing Tutorials, which
>>> could be against the template too.
>>>
>>> Jo will update the calendar invite - next meeting in 2 weeks. It appears
>>> some people's calendars need refreshing.
>>>
>>> [1] List of geonetwork doc pages and their status
>>> https://docs.google.com/spreadsheets/d/1l5FwIj5wpr7QUGsmVNJsvvK5KenMEhHmdL_svfeqDXk/edit#gid=1668835383
>>>
>>> [2] The four key doc types https://www.divio.com/blog/documentation/
>>>
>>> [3] The Good Docs Project Templates 0.1 in Google Docs:
>>> https://drive.google.com/drive/folders/1Z-UORVQp9TXxU94SphfMh1UkmE7yEom8
>>>
>>> [4] The Good Docs Project Templates more recent source (view raw source
>>> to see comments):
>>> https://github.com/thegooddocsproject/templates/tree/master/how-to
>>>
>>>
>>> --
>>> Cameron Shorter
>>> Technology Demystifier
>>> Open Technologies and Geospatial Consultant
>>>
>>> M +61 (0) 419 142 254
>>>
>> _______________________________________________
>> SeasonOfDocs mailing list
>> SeasonOfDocs at lists.osgeo.org
>> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
> _______________________________________________
> SeasonOfDocs mailing list
> SeasonOfDocs at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/seasonofdocs

-- 
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant

M +61 (0) 419 142 254