[OSGeoLive] First QuickStart review completed: GPSPrune

[Felicity Brand]

Thanks Cameron, good points about adding reasons and explanation for
my suggestions. I will do that.

I have modified the template to remove uDig specific references and
make it a bit easier to scan. I did keep a lot of the procedural
content however, so that there are examples for the Writing Tips. It's
a tricky one, and I'll be keen to see what we do over in The Good Docs
Project about this issue.

I see a flaw in my GitHub process. My GPSPrune PR has been merged
without the comments being actioned, and because of the "Review" line
I added to the file, it makes it look as if the file has been reviewed
and improved.

Perhaps I do need to make changes within the file instead after all. I
might try that for Mapbender and MapSlicer and see how that process
goes. I'm still trying to iron out the flow.

Thanks
Felicity

On Sat, Oct 26, 2019 at 8:51 PM Cameron Shorter
<cameron.shorter at gmail.com> wrote:
>
> Thanks Felicity, comments on your first feedback:
>
> * I like your use of a simple pull request with a reviewer and a bunch
> of comments. While clumsy, I think it is the best process for collecting
> this type of feedback.
>
> * I like the way you are bullet pointing out suggested changes.
>
> * I think it would be helpful to provide reasons for some of your
> suggestions, typically "in line with ..." or "to improve readability" or
> "in line with our style guide" (if we were to select a preferred style
> guide).
>
> * I like the idea of a template quickstart, but think it should not be
> tied to a specific project. As Erin picked up in the good docs project:
> 1. It implies favouritism, 2. It becomes out of date when the project
> updates. (Notably this udig quickstart is out of date, referencing an
> old version of the osgeolive release.)
>
> On 25/10/19 1:34 pm, Felicity Brand wrote:
> > Hello,
> >
> > I am excited to say that I have finally completed the first QuickStart
> > review as a proof of concept to test the process.
> >
> > Activityworkshop, thank you for being the guinea pig.
> >
> > I have created a PR on GitHub: https://github.com/OSGeo/OSGeoLive-doc/pull/515
> > And I have created its partner ticket in trac:
> > https://trac.osgeo.org/osgeolive/ticket/2187#ticket
> >
> > The action items for the document owner are in a comment on the Pull
> > Request. I had hoped to be able to comment on things in context, but
> > GitHub doesn't let you work that way, so all the review comments are
> > together and I have formatted them using markdown. I hope it is easy
> > enough to follow.
> >
> > I'm not too sure about the next part of the process. Theoretically, my
> > PR doesn't need to get merged. Document owners will need to make the
> > edits and then have their own PR approved. @Cameron Shorter can you
> > think of a way this might work? @activityworkshop, please let me know
> > what the experience is like at your end.
> >
> > Thank you
> > Felicity
>
> --
> Cameron Shorter
> Technology Demystifier
> Open Technologies and Geospatial Consultant
>
> M +61 (0) 419 142 254
>