Quick starts status update (Google Season of Docs)

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

Quick starts status update (Google Season of Docs)

Felicity Brand
Hello all,

I've been working on the Quick Start template and there are a couple
of questions I wanted to ask.

I have come across the Sphinx markup :guilabel: and :menuselection:
What do we gain by using these? It seems to me something extra to
type. I understand we can then render them a particular way, but if
it's just going to be rendered bold it feels like more effort than
it's worth. But please let me know if I'm missing something in my
understanding here. Do we want to continue using this convention?

I'd like some guidance on my process next.
At a previous meeting, we agreed that the best way for me to give
feedback would be GitHub comments. I think I need to raise a PR in
order to be able to comment on the code. But I didn't intend on making
any changes...so I'm not sure what would go in my PR. Unless I make
some kind of nominal change that we all agree on beforehand? I suppose
we'll want a PR per project quick start - so that would be maybe 50
PRs. Is that cool with everyone?

My intention was to also create about 50 trac tickets, one for each
project. These would include the details of my rating score of the
quick start and perhaps a link to the relevant GitHub PR. I thought it
would be appropriate to have trac as well as GitHub so that anyone
could look at the trac ticket and pick up from there. What do folk
think about that?

I'm not ready to start any GitHub work yet, but I wanted to get
discussion on this rolling so that I know what to do when that time
comes.

Thanks
Felicity
_______________________________________________
osgeolive mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/osgeolive
Reply | Threaded
Open this post in threaded view
|

Re: Quick starts status update (Google Season of Docs)

Nicolas Roelandt
Hi Felicity,

Thanks for working on this and asking things !

For the Sphinx markup, I don't have a good response. I did like it was made as it is part of the process.
But this can be questioned !

For your comments, if you don't want to change code and make a PR, fill an issue in Trac so we can comment on it.

Trac is our main issue tracker so I think that it is better to fill your projects tickets there too.

Thanks again,

Warm regards,

Nicolas Roelandt

Le lun. 7 oct. 2019 à 06:57, Felicity Brand <[hidden email]> a écrit :
Hello all,

I've been working on the Quick Start template and there are a couple
of questions I wanted to ask.

I have come across the Sphinx markup :guilabel: and :menuselection:
What do we gain by using these? It seems to me something extra to
type. I understand we can then render them a particular way, but if
it's just going to be rendered bold it feels like more effort than
it's worth. But please let me know if I'm missing something in my
understanding here. Do we want to continue using this convention?

I'd like some guidance on my process next.
At a previous meeting, we agreed that the best way for me to give
feedback would be GitHub comments. I think I need to raise a PR in
order to be able to comment on the code. But I didn't intend on making
any changes...so I'm not sure what would go in my PR. Unless I make
some kind of nominal change that we all agree on beforehand? I suppose
we'll want a PR per project quick start - so that would be maybe 50
PRs. Is that cool with everyone?

My intention was to also create about 50 trac tickets, one for each
project. These would include the details of my rating score of the
quick start and perhaps a link to the relevant GitHub PR. I thought it
would be appropriate to have trac as well as GitHub so that anyone
could look at the trac ticket and pick up from there. What do folk
think about that?

I'm not ready to start any GitHub work yet, but I wanted to get
discussion on this rolling so that I know what to do when that time
comes.

Thanks
Felicity
_______________________________________________
osgeolive mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/osgeolive


--
Bien cordialement,

Nicolas Roelandt
mail: [hidden email]
mobile: +33 (0)6 42 40 42 55
twitter: @RoelandtN42

_______________________________________________
osgeolive mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/osgeolive
Reply | Threaded
Open this post in threaded view
|

Re: Quick starts status update (Google Season of Docs)

Cameron Shorter

Hi Felicity,

Re labels, I don't feel strongly about whether we use them or not, but whatever we do, we aim to be consistent, and document our decision in our Quickstart template. I'd probably err on:

1. Adopting whatever is commonly used by all projects.

2. Keeping our use of labels simple (ie, not have them if it is not adding much value).

--

Your suggestions for raising 50 trac tickets and 50 pull requests sound reasonable for me. I suggest doing one top-to-bottom and get feedback before continuing with the rest.

Also, after reviewing a project's Quickstart, I suggest sending a direct email to that project's point of contact(s). Most don't monitor the OSGeoLive email list closely and will appreciate the email.

You will also get a range of opinions on how hands on each person will be with their project. Some will accept every suggestion you make. Others will take it as guidance and then rewrite.

Cheers, Cameron

On 7/10/19 6:10 pm, Nicolas Roelandt wrote:
Hi Felicity,

Thanks for working on this and asking things !

For the Sphinx markup, I don't have a good response. I did like it was made as it is part of the process.
But this can be questioned !

For your comments, if you don't want to change code and make a PR, fill an issue in Trac so we can comment on it.

Trac is our main issue tracker so I think that it is better to fill your projects tickets there too.

Thanks again,

Warm regards,

Nicolas Roelandt

Le lun. 7 oct. 2019 à 06:57, Felicity Brand <[hidden email]> a écrit :
Hello all,

I've been working on the Quick Start template and there are a couple
of questions I wanted to ask.

I have come across the Sphinx markup :guilabel: and :menuselection:
What do we gain by using these? It seems to me something extra to
type. I understand we can then render them a particular way, but if
it's just going to be rendered bold it feels like more effort than
it's worth. But please let me know if I'm missing something in my
understanding here. Do we want to continue using this convention?

I'd like some guidance on my process next.
At a previous meeting, we agreed that the best way for me to give
feedback would be GitHub comments. I think I need to raise a PR in
order to be able to comment on the code. But I didn't intend on making
any changes...so I'm not sure what would go in my PR. Unless I make
some kind of nominal change that we all agree on beforehand? I suppose
we'll want a PR per project quick start - so that would be maybe 50
PRs. Is that cool with everyone?

My intention was to also create about 50 trac tickets, one for each
project. These would include the details of my rating score of the
quick start and perhaps a link to the relevant GitHub PR. I thought it
would be appropriate to have trac as well as GitHub so that anyone
could look at the trac ticket and pick up from there. What do folk
think about that?

I'm not ready to start any GitHub work yet, but I wanted to get
discussion on this rolling so that I know what to do when that time
comes.

Thanks
Felicity
_______________________________________________
osgeolive mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/osgeolive


--
Bien cordialement,

Nicolas Roelandt
mail: [hidden email]
mobile: +33 (0)6 42 40 42 55
twitter: @RoelandtN42

_______________________________________________
osgeolive mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/osgeolive
-- 
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant

M +61 (0) 419 142 254

_______________________________________________
osgeolive mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/osgeolive
Reply | Threaded
Open this post in threaded view
|

Re: Quick starts status update (Google Season of Docs)

Seth G-2
In reply to this post by Felicity Brand
Hi Felicity,

With regards to the Sphinx markup, using the directives would have the following advantages:

- allow a consistent way to show menu selections (or any conventions such as File > Open, File -> Open, File | Open could be used. It is probably simplest to stay with the Sphinx convention rather than create a new one.
- allow a theme to be applied across all the docs in the future e.g. the GUI labels at https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#inline-markup
- shortcut keys can be applied to the labels e.g. button :guilabel:`&Start`

It may also help with translating and matching GUI labels in different languages.

If they are already widely used I'd be in favour of keeping them  and applying elsewhere.

Seth

--
web:http://geographika.co.uk
twitter: @geographika

On Mon, Oct 7, 2019, at 6:56 AM, Felicity Brand wrote:

> Hello all,
>
> I've been working on the Quick Start template and there are a couple
> of questions I wanted to ask.
>
> I have come across the Sphinx markup :guilabel: and :menuselection:
> What do we gain by using these? It seems to me something extra to
> type. I understand we can then render them a particular way, but if
> it's just going to be rendered bold it feels like more effort than
> it's worth. But please let me know if I'm missing something in my
> understanding here. Do we want to continue using this convention?
>
> I'd like some guidance on my process next.
> At a previous meeting, we agreed that the best way for me to give
> feedback would be GitHub comments. I think I need to raise a PR in
> order to be able to comment on the code. But I didn't intend on making
> any changes...so I'm not sure what would go in my PR. Unless I make
> some kind of nominal change that we all agree on beforehand? I suppose
> we'll want a PR per project quick start - so that would be maybe 50
> PRs. Is that cool with everyone?
>
> My intention was to also create about 50 trac tickets, one for each
> project. These would include the details of my rating score of the
> quick start and perhaps a link to the relevant GitHub PR. I thought it
> would be appropriate to have trac as well as GitHub so that anyone
> could look at the trac ticket and pick up from there. What do folk
> think about that?
>
> I'm not ready to start any GitHub work yet, but I wanted to get
> discussion on this rolling so that I know what to do when that time
> comes.
>
> Thanks
> Felicity
> _______________________________________________
> osgeolive mailing list
> [hidden email]
> https://lists.osgeo.org/mailman/listinfo/osgeolive
>
_______________________________________________
osgeolive mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/osgeolive
Reply | Threaded
Open this post in threaded view
|

Re: Quick starts status update (Google Season of Docs)

Felicity Brand
In reply to this post by Cameron Shorter
Hello all,

I am about to do my proof of concept trial with 2 Quick Starts. I
thought I'd choose MapSlicer and Mapbender because both Astrid and
Angelos expressed an interest in improving the Quickstarts for their
projects :-)

This should give me good practice to see if the GitHub process works
out, as well as creating the trac tickets.

Before I do anything, here is what I thought the trac ticket might
look like - please let me know if any of these values should be
different:

*Summary = Update the [Project Name] Quick Start
*Description = The [Project Name] Quick Start was reviewed by flicstar
as part of the Google Season of Docs in October 2019.
The high level results of this review are that:
- It has an Overview, Procedure and Things to Try section - which is good.
- It is missing the Next Steps section and requires minor updates in
the Procedure section.
Please see comments in GitHub on this PR: <Insert PR link>
*Type = Task
*Priority = Normal
*Milestone = OSGeoLive 14.0
*Component = Documentation (or OSGeoLive?)
*Keywords - should I add a keyword (like "documentation")?
*Will I assign it to an owner - like the contact person for the project?

Is there a bulk way to create trac tickets?

Thanks
Felicity

On Mon, Oct 7, 2019 at 6:22 PM Cameron Shorter
<[hidden email]> wrote:

>
> Hi Felicity,
>
> Re labels, I don't feel strongly about whether we use them or not, but whatever we do, we aim to be consistent, and document our decision in our Quickstart template. I'd probably err on:
>
> 1. Adopting whatever is commonly used by all projects.
>
> 2. Keeping our use of labels simple (ie, not have them if it is not adding much value).
>
> --
>
> Your suggestions for raising 50 trac tickets and 50 pull requests sound reasonable for me. I suggest doing one top-to-bottom and get feedback before continuing with the rest.
>
> Also, after reviewing a project's Quickstart, I suggest sending a direct email to that project's point of contact(s). Most don't monitor the OSGeoLive email list closely and will appreciate the email.
>
> You will also get a range of opinions on how hands on each person will be with their project. Some will accept every suggestion you make. Others will take it as guidance and then rewrite.
>
> Cheers, Cameron
>
> On 7/10/19 6:10 pm, Nicolas Roelandt wrote:
>
> Hi Felicity,
>
> Thanks for working on this and asking things !
>
> For the Sphinx markup, I don't have a good response. I did like it was made as it is part of the process.
> But this can be questioned !
>
> For your comments, if you don't want to change code and make a PR, fill an issue in Trac so we can comment on it.
>
> Trac is our main issue tracker so I think that it is better to fill your projects tickets there too.
>
> Thanks again,
>
> Warm regards,
>
> Nicolas Roelandt
>
> Le lun. 7 oct. 2019 à 06:57, Felicity Brand <[hidden email]> a écrit :
>>
>> Hello all,
>>
>> I've been working on the Quick Start template and there are a couple
>> of questions I wanted to ask.
>>
>> I have come across the Sphinx markup :guilabel: and :menuselection:
>> What do we gain by using these? It seems to me something extra to
>> type. I understand we can then render them a particular way, but if
>> it's just going to be rendered bold it feels like more effort than
>> it's worth. But please let me know if I'm missing something in my
>> understanding here. Do we want to continue using this convention?
>>
>> I'd like some guidance on my process next.
>> At a previous meeting, we agreed that the best way for me to give
>> feedback would be GitHub comments. I think I need to raise a PR in
>> order to be able to comment on the code. But I didn't intend on making
>> any changes...so I'm not sure what would go in my PR. Unless I make
>> some kind of nominal change that we all agree on beforehand? I suppose
>> we'll want a PR per project quick start - so that would be maybe 50
>> PRs. Is that cool with everyone?
>>
>> My intention was to also create about 50 trac tickets, one for each
>> project. These would include the details of my rating score of the
>> quick start and perhaps a link to the relevant GitHub PR. I thought it
>> would be appropriate to have trac as well as GitHub so that anyone
>> could look at the trac ticket and pick up from there. What do folk
>> think about that?
>>
>> I'm not ready to start any GitHub work yet, but I wanted to get
>> discussion on this rolling so that I know what to do when that time
>> comes.
>>
>> Thanks
>> Felicity
>> _______________________________________________
>> osgeolive mailing list
>> [hidden email]
>> https://lists.osgeo.org/mailman/listinfo/osgeolive
>
>
>
> --
> Bien cordialement,
>
> Nicolas Roelandt
> mail: [hidden email]
> mobile: +33 (0)6 42 40 42 55
> twitter: @RoelandtN42
>
> _______________________________________________
> osgeolive mailing list
> [hidden email]
> https://lists.osgeo.org/mailman/listinfo/osgeolive
>
> --
> Cameron Shorter
> Technology Demystifier
> Open Technologies and Geospatial Consultant
>
> M +61 (0) 419 142 254
>
> _______________________________________________
> osgeolive mailing list
> [hidden email]
> https://lists.osgeo.org/mailman/listinfo/osgeolive
_______________________________________________
osgeolive mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/osgeolive
Reply | Threaded
Open this post in threaded view
|

Re: Quick starts status update (Google Season of Docs)

Cameron Shorter
Hi Felicity, comments inline:

On 11/10/19 3:01 pm, Felicity Brand wrote:
> Hello all,
>
> I am about to do my proof of concept trial with 2 Quick Starts. I
> thought I'd choose MapSlicer and Mapbender because both Astrid and
> Angelos expressed an interest in improving the Quickstarts for their
> projects :-)
Good idea to start with projects which have a volunteer. Based on that
criteria, [hidden email] has offered to help with gps_prune.
>
> This should give me good practice to see if the GitHub process works
> out, as well as creating the trac tickets.
>
> Before I do anything, here is what I thought the trac ticket might
> look like - please let me know if any of these values should be
> different:
>
> *Summary = Update the [Project Name] Quick Start
Good.
> *Description = The [Project Name] Quick Start was reviewed by flicstar
> as part of the Google Season of Docs in October 2019.
> The high level results of this review are that:
> - It has an Overview, Procedure and Things to Try section - which is good.
> - It is missing the Next Steps section and requires minor updates in
> the Procedure section.
> Please see comments in GitHub on this PR: <Insert PR link>
Sounds good.
> *Type = Task
While "task" is ok, I'd err on categorising as a "bug", especially if
the docs are breaking the template structure by not aligning with best
practice headings and guidelines.
> *Priority = Normal
Good
> *Milestone = OSGeoLive 14.0
Good
> *Component = Documentation (or OSGeoLive?)
Yes, "Documentation"
> *Keywords - should I add a keyword (like "documentation")?
We don't need to fill this in, but it could be handy to add "quickstart"
so we can search of quickstart reviews in future.
> *Will I assign it to an owner - like the contact person for the project?

We typically have not done this in the past. You likely won't know the
username of 1/4 to 1/2 of the contact people. However, you could add
people's email addressed to the "CC" tab. (Note, many people won't
notice this auto email.)

So follow up with an email to people directly, with a personal email
title, stating something like:

"I've just raised comments on the [Project] quickstart. Would you mind
having a look? I'm keen to process feedback before my SeasonOfDocs
stipend finishes in November. If you could provide feedback within the
next week or 2, that would be great.

Thanks, Felicity, SeasonOfDocs Tech Writer for OSGeo"

>
> Is there a bulk way to create trac tickets?
Not that I'm aware of, but I haven't looked.

>
> Thanks
> Felicity
>
> On Mon, Oct 7, 2019 at 6:22 PM Cameron Shorter
> <[hidden email]> wrote:
>> Hi Felicity,
>>
>> Re labels, I don't feel strongly about whether we use them or not, but whatever we do, we aim to be consistent, and document our decision in our Quickstart template. I'd probably err on:
>>
>> 1. Adopting whatever is commonly used by all projects.
>>
>> 2. Keeping our use of labels simple (ie, not have them if it is not adding much value).
>>
>> --
>>
>> Your suggestions for raising 50 trac tickets and 50 pull requests sound reasonable for me. I suggest doing one top-to-bottom and get feedback before continuing with the rest.
>>
>> Also, after reviewing a project's Quickstart, I suggest sending a direct email to that project's point of contact(s). Most don't monitor the OSGeoLive email list closely and will appreciate the email.
>>
>> You will also get a range of opinions on how hands on each person will be with their project. Some will accept every suggestion you make. Others will take it as guidance and then rewrite.
>>
>> Cheers, Cameron
>>
>> On 7/10/19 6:10 pm, Nicolas Roelandt wrote:
>>
>> Hi Felicity,
>>
>> Thanks for working on this and asking things !
>>
>> For the Sphinx markup, I don't have a good response. I did like it was made as it is part of the process.
>> But this can be questioned !
>>
>> For your comments, if you don't want to change code and make a PR, fill an issue in Trac so we can comment on it.
>>
>> Trac is our main issue tracker so I think that it is better to fill your projects tickets there too.
>>
>> Thanks again,
>>
>> Warm regards,
>>
>> Nicolas Roelandt
>>
>> Le lun. 7 oct. 2019 à 06:57, Felicity Brand <[hidden email]> a écrit :
>>> Hello all,
>>>
>>> I've been working on the Quick Start template and there are a couple
>>> of questions I wanted to ask.
>>>
>>> I have come across the Sphinx markup :guilabel: and :menuselection:
>>> What do we gain by using these? It seems to me something extra to
>>> type. I understand we can then render them a particular way, but if
>>> it's just going to be rendered bold it feels like more effort than
>>> it's worth. But please let me know if I'm missing something in my
>>> understanding here. Do we want to continue using this convention?
>>>
>>> I'd like some guidance on my process next.
>>> At a previous meeting, we agreed that the best way for me to give
>>> feedback would be GitHub comments. I think I need to raise a PR in
>>> order to be able to comment on the code. But I didn't intend on making
>>> any changes...so I'm not sure what would go in my PR. Unless I make
>>> some kind of nominal change that we all agree on beforehand? I suppose
>>> we'll want a PR per project quick start - so that would be maybe 50
>>> PRs. Is that cool with everyone?
>>>
>>> My intention was to also create about 50 trac tickets, one for each
>>> project. These would include the details of my rating score of the
>>> quick start and perhaps a link to the relevant GitHub PR. I thought it
>>> would be appropriate to have trac as well as GitHub so that anyone
>>> could look at the trac ticket and pick up from there. What do folk
>>> think about that?
>>>
>>> I'm not ready to start any GitHub work yet, but I wanted to get
>>> discussion on this rolling so that I know what to do when that time
>>> comes.
>>>
>>> Thanks
>>> Felicity
>>> _______________________________________________
>>> osgeolive mailing list
>>> [hidden email]
>>> https://lists.osgeo.org/mailman/listinfo/osgeolive
>>
>>
>> --
>> Bien cordialement,
>>
>> Nicolas Roelandt
>> mail: [hidden email]
>> mobile: +33 (0)6 42 40 42 55
>> twitter: @RoelandtN42
>>
>> _______________________________________________
>> osgeolive mailing list
>> [hidden email]
>> https://lists.osgeo.org/mailman/listinfo/osgeolive
>>
>> --
>> Cameron Shorter
>> Technology Demystifier
>> Open Technologies and Geospatial Consultant
>>
>> M +61 (0) 419 142 254
>>
>> _______________________________________________
>> osgeolive mailing list
>> [hidden email]
>> https://lists.osgeo.org/mailman/listinfo/osgeolive

--
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant

M +61 (0) 419 142 254

_______________________________________________
osgeolive mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/osgeolive