Season of Docs Ideas 2019 - Revision history

Jocook: /* GeoNetwork */

2019-08-16T10:57:51Z

GeoNetwork

Wiki-Sunk8 at 19:16, 14 August 2019

2019-08-14T19:16:18Z

Wiki-Camerons: /* Reduce writer barrier to entry */

2019-08-03T00:17:21Z

Reduce writer barrier to entry

Jocook: /* GeoNetwork */

2019-07-12T10:12:16Z

GeoNetwork

Wiki-Genuchten: /* Examples of existing portal-specific guidance: */

2019-07-12T09:41:53Z

Examples of existing portal-specific guidance:

Wiki-ByronCinNZ: /* GeoNetwork */

2019-07-01T02:20:42Z

GeoNetwork

Wiki-Camerons: /* Best practice templates */

2019-06-29T20:24:21Z

Best practice templates

Wiki-Genuchten: /* GeoNetwork */

2019-06-28T14:35:54Z

GeoNetwork

Jocook: /* GeoNetwork */

2019-06-28T11:23:01Z

GeoNetwork

Wiki-Camerons: /* Best practice templates */

2019-06-25T12:24:07Z

Best practice templates

@@ Line 182: / Line 182: @@
 https://docs.google.com/spreadsheets/d/1l5FwIj5wpr7QUGsmVNJsvvK5KenMEhHmdL_svfeqDXk/edit?usp=sharing
-* ''NOTE: The fix contributed to correct the "Edit on GitHub" link does not seem to be active yet.  Replace "en" with "source" in the URL and you are good to go. For example https://github.com/geonetwork/doc/blob/develop/en/annexes/standards/dublin-core/index.rst should be https://github.com/geonetwork/doc/blob/develop/source/annexes/standards/dublin-core/index.rst''
+==== GeoNetwork Quick Start Guide ====
-The link below is to a Google Docs version of the Quick Start chapter of the current Geonetwork documentation. The sharing link below allows you to comment only. This will remain active until such time as we're ready to build in the suggested changes.
+The GeoNetwork Quick Start Guide was updated for the upcoming release of OSGeo:Live 13.0. See https://github.com/OSGeo/OSGeoLive-doc/blob/master/doc/quickstart/geonetwork_quickstart.rst. There is an equivalent to this at https://geonetwork-opensource.org/manuals/trunk/en/user-guide/quick-start/index.html but it needs adapting to use the latest version of GeoNetwork (OSGeo:Live is a version behind). There's a Google Doc that was the basis for the update, which is available for commenting below.
 https://docs.google.com/document/d/117WkUYJUaOcCjxglcfKFkSKq6axyRKuO8iL9gLnvwYU/edit?usp=sharing

@@ Line 53: / Line 53: @@
 # '''Felicity Brand: [Volunteer Writer]''' New mum and freelance part-time technical writer. I'm keen to add value wherever I can. I am cool with writing, editing, structuring, info architecture, usability testing, producing videos, making users feel confident and comfortable, etc.
 # '''Thomas Starnes: [Volunteer Writer]''' Geospatial scientist working with a wildlife conservation nonprofit. Sometimes see sections of QGIS guidance documents which could do with improving, but happy to be directed. Heading up Cambridge Conservation Forum GIS group and considering training QGIS through the FOSS4G Academy.
 * ... add your name here

@@ Line 119: / Line 119: @@
 Potential resources:
-* [https://riedmann.dev/2019/06/02/GitGud.html Learning git concepts]
+* [https://dev.to/unseenwizzard/learn-git-concepts-not-commands-4gjc Learning git concepts]
 * [http://docutils.sourceforge.net/docs/user/rst/quickstart.html A ReStructuredText Primer] and [http://docutils.sourceforge.net/docs/user/rst/quickref.html#section-structure Examples].

← Older revision		Revision as of 10:12, 12 July 2019
Line 182:		Line 182:

	* ''NOTE: The fix contributed to correct the "Edit on GitHub" link does not seem to be active yet. Replace "en" with "source" in the URL and you are good to go. For example https://github.com/geonetwork/doc/blob/develop/en/annexes/standards/dublin-core/index.rst should be https://github.com/geonetwork/doc/blob/develop/source/annexes/standards/dublin-core/index.rst''		* ''NOTE: The fix contributed to correct the "Edit on GitHub" link does not seem to be active yet. Replace "en" with "source" in the URL and you are good to go. For example https://github.com/geonetwork/doc/blob/develop/en/annexes/standards/dublin-core/index.rst should be https://github.com/geonetwork/doc/blob/develop/source/annexes/standards/dublin-core/index.rst''
		+
		+	The link below is to a Google Docs version of the Quick Start chapter of the current Geonetwork documentation. The sharing link below allows you to comment only. This will remain active until such time as we're ready to build in the suggested changes.
		+
		+	https://docs.google.com/document/d/117WkUYJUaOcCjxglcfKFkSKq6axyRKuO8iL9gLnvwYU/edit?usp=sharing

@@ Line 200: / Line 200: @@
 ==== Examples of existing portal-specific guidance: ====
 * Scottish Spatial Data Infrastructure: https://scottish-sdi-metadata-portal.readthedocs.io/en/3.4.x/
-* Dutch SDI: https://www.nationaalgeoregister.nl/geonetwork/srv/dut/catalog.search#/about
+* Dutch SDI: https://www.nationaalgeoregister.nl/geonetwork/srv/dut/catalog.search#/about https://pdok-ngr.readthedocs.io
 ==Other OSGeo Project Docs ==

@@ Line 172: / Line 172: @@
 We'd like to reduce the barrier to entry to adding documentation. We have started tagging "easy to resolve" issues in our GitHub repository but this has not gained much traction yet.
-Season of Docs ideas for GeoNetwork include:
+==== Season of Docs ideas for GeoNetwork include: ====
 * Geonetwork team to scope and create issues for incomplete documentation (drawing from doc review and pull requests).
 * Geonetwork team to reach out to, encourage and support co-contributions to documentation from the user base.
@@ Line 182: / Line 193: @@
 * Writers to work through documentation issue list.
-Resources:
+==== Resources: ====
 * Source code of existing english docs: https://github.com/geonetwork/doc (translations are managed via transifex)
 * Existing docs: https://geonetwork-opensource.org/docs.html
 * Extra developer docs: https://github.com/geonetwork/core-geonetwork/wiki#documentation
-Examples of existing portal-specific guidance:
+==== Examples of existing portal-specific guidance: ====
 * Scottish Spatial Data Infrastructure: https://scottish-sdi-metadata-portal.readthedocs.io/en/3.4.x/
 * Dutch SDI: https://www.nationaalgeoregister.nl/geonetwork/srv/dut/catalog.search#/about

@@ Line 94: / Line 94: @@
 Potential resources:
-* [http://cameronshorter.blogspot.com/2019/02/inspiring-techies-to-become-great.html Inspiring great technical docs, using templates]. Vision as a presentation - 8 min read.
+* Cameron Shorter's [http://cameronshorter.blogspot.com/2019/02/inspiring-techies-to-become-great.html Inspiring great technical docs, using templates] Vision as a presentation - 8 min read.
 * Daniele Procida’s [https://www.divio.com/blog/documentation/ What nobody tells you about documentation]. ([https://www.youtube.com/watch?v=azf6yzuJt54 videoed at PyCon 2017]).
 * [https://lisafc.github.io/tw101-reading/ Pre-reading for a Tech Writing 101 course] which has been presented by Google Tech Writers.
 * [https://github.com/San-Francisco-Write-The-Docs/lone-writers-guide Lone Writers Guide] - Practical tips for tech writers: "Milestones to hit in the first 30, 60, and 90 days".
-* [http://cameronshorter.blogspot.com/2018/06/technical-documentation-writing.html Document type definitions].
+* Example of [http://cameronshorter.blogspot.com/2018/06/technical-documentation-writing.html Document type definitions].
 * [https://wiki.osgeo.org/wiki/OSGeoLive_AddProject#Documentation Writing instructions for OSGeoLive Project Overviews and Quickstarts].
-* The [https://www.writethedocs.org/about/stay-connected/ Write-The-Docs community] are a likely source of potential co-contributors and defacto owners of such templates.
+* [https://www.writethedocs.org/guide/ WriteTheDocs Guide]
 * [https://www.cebm.net/wp-content/uploads/2016/09/Blooms-Taxonomy-Teacher-Planning-Kit.pdf Bloom’s Taxonomy: Teacher Planning Kit] is helpful for selecting the language for training.
 * [https://github.com/mdyd-dev/nearme-documentation/tree/master/marketplace_builder/views/pages/doc-templates Nearme writing templates] with [https://www.platform-os.com/blog/post/blog/building-our-documentation-site-on-platformos-part-2-content-production-and-layouts accompanying blog post].
@@ Line 108: / Line 109: @@
 * [https://twitter.com/sapinker/status/1084490338629242880 Twitter thread on good writing that can equally be applied to technical documentation]
 * [https://twitter.com/JessTelford/status/992756386160234497 Another twitter thread on words to avoid when writing documentation]
-* [https://github.com/kylelobo/The-Documentation-Compendium The Documentation Compendium]
+* [https://github.com/kylelobo/The-Documentation-Compendium The Documentation Compendium] - Kyle Lobo
 * [http://blog.developer.atlassian.com/writing-great-docs-for-your-app/ Guide to writing docs using templates - Becky Todd, Atlassian]