Vicky's suggestion of improving the osgeolive wiki writing guidelines
are good. The existing guidelines have a strong focus on the mechanics
of the publishing process (how to use variable names etc).
The value Felicity can bring is to bring the perspective of a user (non
developer) to getting started, and also to help with writing structure
and style. (The words rather than the process).
What is emerging from the tech writers from TheGoodDocsProcess is value
in having an exemplar template. While the existing Quickstarts are
valuable, they will not necessarily still be the best practice in 3
years time. It is easier for the core writers to maintain one best
practice template and get developers/users to write against that, rather
than having to update all 50 projects when best practices evolve.
So I'm in favour of keeping a Quickstart template.
I'm taking this conversation back to the email list (originally in gitea?)
On 2/11/19 6:21 am, Felicity Brand wrote:
Thanks for this cvvergara.
I'm happy to do as you suggest and it all makes sense to me. I'd need
to remove the template from the repo because you're looking at the one
in gitea and it actually did get added over in GitHub.
In a new PR which is still awaiting merge
(https://github.com/OSGeo/OSGeoLive-doc/pull/516) I tried to remove as
much of the uDig content as I could, but it does still contain some
and I felt uncomfortable about it.
CC'ing Cameron because he's mentoring me through the Season of Docs
period. Cameron, do you have any thoughts to add here?
Thanks
Felicity
On Sat, Nov 2, 2019 at 2:28 AM cvvergara <nore...@osgeo.org> wrote:
The build will pass because the file is not included on the build. Its a copy
of udig:
it has udig’s author names
it has is for osgeolive version for 5.0 The only difference is that it has
writing tips
From my perspective it does not add more value to the repository: At this
point in time with so many quickstarts, any quickstart can work as a template
Its just a matter of adjusting to what a new project needs.
We do have guidelines on how to document a project here:
https://trac.osgeo.org/osgeolive/wiki/How%20to%20document%20a%20project
https://trac.osgeo.org/osgeolive/wiki/How to document the quickstart file
https://trac.osgeo.org/osgeolive/wiki/How%20to%20document%20the%20overview%20file
My personal feeling is that it would be better to double check the guidelines
and complete them:
Making sure that the writing tips are there
Add writing tips that are missing
Changing those files does not need a PR, you just need to be an OSGeo member
(which you are otherwise you could not have done this PR) and we trust that
OSGeo members will do their best in their volunteering, so you don’t need
approval when you modify the files.
---
View it on Gitea.
--
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant
M +61 (0) 419 142 254
_______________________________________________
osgeolive mailing list
osgeolive@lists.osgeo.org
https://lists.osgeo.org/mailman/listinfo/osgeolive
