[SeasonOfDocs] GeoNetwork Docs meeting notes

[María Arias de Reyna]

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