Date   
Re: Git member access for Morgan Craft

Morgan Craft
 

Thanks for adding me to the project, look forward to future
collaboration(s) with everyone.

Tested my new permissions and officially closed PR/113.

Cheers,
Morgan

On Fri, May 29, 2020 at 6:22 PM Cameron Shorter <cameron.shorter@...>
wrote:

After consulting with our Project Steering Committee, we are inviting
Mogan to have git member access to TheGoodDocsProject.
This will give him access to accept/reject pull requests.
I've been impressed with the quality of advice Morgan has been providing
both in email and in github, and trust that he will use this privilege
wisely, and in consultation with the rest of our community.
He also confirmed to me that he intends to stick around with the project
for a while, which will be great for us.

Welcome Morgan.
I suggest testing your access by wrapping up this pull request:
https://github.com/thegooddocsproject/templates/pull/113

--
Cameron Shorter
Technical Writer, Google


Git member access for Morgan Craft

Cameron Shorter
 

After consulting with our Project Steering Committee, we are inviting Mogan
to have git member access to TheGoodDocsProject.
This will give him access to accept/reject pull requests.
I've been impressed with the quality of advice Morgan has been providing
both in email and in github, and trust that he will use this privilege
wisely, and in consultation with the rest of our community.
He also confirmed to me that he intends to stick around with the project
for a while, which will be great for us.

Welcome Morgan.
I suggest testing your access by wrapping up this pull request:
https://github.com/thegooddocsproject/templates/pull/113

--
Cameron Shorter
Technical Writer, Google

Re: Proposal to give Morgan Craft contributor permissions

Jared Morgan
 

+1 seems like a good choice to let him help

On Thu, 28 May 2020, 08:02 Cameron Shorter, <cameron.shorter@...>
wrote:

Folks,
I propose to give Morgan Craft contributor access to our github
repositories, which will give him access to accept/reject pull requests.
+1 from me.

I've been impressed with the quality of advice Morgan has been providing
both in email and in github, and trust that he will use this privilege
wisely, and in consultation with the rest of our community.
He also confirmed to me that he intends to stick around with the project
for a while, which will be great for us.

Unless there are objections, I plan to set this up in ~ 24 to 48 hours.

--
Cameron Shorter
Technical Writer, Google



Proposal to give Morgan Craft contributor permissions

Cameron Shorter
 

Folks,
I propose to give Morgan Craft contributor access to our github
repositories, which will give him access to accept/reject pull requests.
+1 from me.

I've been impressed with the quality of advice Morgan has been providing
both in email and in github, and trust that he will use this privilege
wisely, and in consultation with the rest of our community.
He also confirmed to me that he intends to stick around with the project
for a while, which will be great for us.

Unless there are objections, I plan to set this up in ~ 24 to 48 hours.

--
Cameron Shorter
Technical Writer, Google

Integrating a git backend to a word processor front end

Cameron Shorter
 

Over the last few days I've had separate conversations with Kevin and Chris
(CCed), as well as others within TheGoodDocsProject.
I think this is a super painful problem for almost all technical writers at
some point, and would be hugely valuable for the world if a fix could be
found.
This email is primarily an introduction, and introducing a space to share
ideas.
Kevin, Chris, you were both sharing implementation suggestions, which I
encourage you to expand upon here.
I've called the problem out in the "Tech Writer Patterns and Tasks" [1]
summary doc which I've invited people to comment on.
Details on signing up to TheGoodDocsProject are here [2].

[1]
https://docs.google.com/document/d/1Uo3Rcc-rRaN4kmJpqwtUaVRJmDbYI4TkwjuNWNuBu9A/edit#heading=h.i98xo49cbv
[2] https://thegooddocsproject.dev/contact.html


--
Cameron Shorter,
Technical Writer, ChromeOS Platforms

Re: Interview with Felicity Brand - and a wrap for TheGoodDocsProject

Jared Morgan
 

That's a great write-up! Congratulations Felicity!

On Wed, 27 May 2020, 17:54 Cameron Shorter, <cameron.shorter@...>
wrote:

Felicity, one of our long time contributors, and Project Steering Committee
member, has had a great article writen about her, the book she is writing,
and a big section on her involvement with TheGoodDocsProject.

https://typo3.org/article/typo3-book-report-whos-writing-the-typo3-book

Nice work Felicity.

--
Cameron Shorter
Technical Writer at Google

M +61 (0) 419 142 254



Re: Should/could we standardize on Common Markdown?

Morgan Craft
 

Sorry holiday and kicking off the week held me up here.

Good call to point this out. I take it for granted that I'm most of the
time just writing GFM style markdown. The pull-request templates
themselves are GFM based because the *task list items* themselves are part
of the extension. We should be safe to adopt the Github Flavored Markdown
approach because GFM is a sub-set of CommonMark the markdown-linter will
work out of the box. If we find ourselves using specific cases of GFM that
are unsupported by the linter rules we can always override the
rules/disable them.

Was thinking as a first step, we could run the common-mark linter on the
current markdown and generate an audit of how/which files needs updated to
get a sense the scope of work in getting us compliant.

-M

On Sun, May 24, 2020 at 4:12 PM Cameron Shorter <cameron.shorter@...>
wrote:

Thanks for the feedback Morgan,
I've now found Github Flavoured Markdown, which extends CommonMark
slightly. It's spec highlights how the changes.
Most notably for me, is that it seems to do a better job at handling
tables.
https://github.github.com/gfm/

On Mon, 25 May 2020 at 00:35, Morgan Craft <mgan59@...> wrote:

I just went through this process of setting up markdown-linters, so I'm
familiar.

The community around the tooling is great, vscode plugins and
github-actions all have adopted common-mark. Think the common-mark spec
is
working with the eco-system of various open-source parsers to get
alignment
and it is happening. They have an active community on github and their
talk
<https://talk.commonmark.org/>.

I'm wondering whether we should add a task to our wishlist "Add git
commithook to check for Common Markdown compliance"?

For us, there are github-actions we can configure so our PRS have a
check, this makes the most sense. Locally, we could setup a github hook
that runs a local-cli command -- there would be some setup work there that
varies depending on your platform and tooling.

Cheers,
M





On Sun, May 24, 2020 at 1:40 AM Cameron Shorter <
cameron.shorter@...>
wrote:

There are multiple variants of Markdown, and I've recently come across
https://commonmark.org/ which attempts to provide an unambiguous
definition
of markdown.
I admire their goals and it appears they have attracted a strong
community.
They aim to achieve interoperability between different markdown
implementations (probably by limiting specific extensions or
interpretations).
For a base project like ours, I'd expect that it would be in our best
interests to align with the Common Markdown format.
Do others have experience with Common Markdown?
Do you have opinions on why we should or should not adopt it?
I'm wondering whether we should add a task to our wishlist "Add git
commit
hook to check for Common Markdown compliance"?

--
Cameron Shorter
Technical Writer at Google

M +61 (0) 419 142 254





--
Cameron Shorter
Technical Writer at Google

M +61 (0) 419 142 254



Weekly meeting and draft list of bounty projects

Cameron Shorter
 

Weekly video conference meeting will be in 10 hours. Email me if you would
like an invite.

Proposed Agenda:

- Progress on Style Guide conversations (Alyssa)
- Status of Open Collective (Erin)
- Draft Bounty task list
<https://docs.google.com/document/d/1Uo3Rcc-rRaN4kmJpqwtUaVRJmDbYI4TkwjuNWNuBu9A/edit#>
(Cameron)
- Other ideas?
- Standing last item: oldest PR
<https://github.com/thegooddocsproject/templates/pull/112>


Further to the existing list of projects put forward for Season of Docs,
I've described more keystone tech writing challenges we face. It is a work
in progress. Feedback welcomed.
https://docs.google.com/document/d/1Uo3Rcc-rRaN4kmJpqwtUaVRJmDbYI4TkwjuNWNuBu9A/edit#



--
Cameron Shorter
Technical Writer at Google

M +61 (0) 419 142 254

Interview with Felicity Brand - and a wrap for TheGoodDocsProject

Cameron Shorter
 

Felicity, one of our long time contributors, and Project Steering Committee
member, has had a great article writen about her, the book she is writing,
and a big section on her involvement with TheGoodDocsProject.

https://typo3.org/article/typo3-book-report-whos-writing-the-typo3-book

Nice work Felicity.

--
Cameron Shorter
Technical Writer at Google

M +61 (0) 419 142 254

Re: Should/could we standardize on Common Markdown?

Cameron Shorter
 

Thanks for the feedback Morgan,
I've now found Github Flavoured Markdown, which extends CommonMark
slightly. It's spec highlights how the changes.
Most notably for me, is that it seems to do a better job at handling
tables.
https://github.github.com/gfm/

On Mon, 25 May 2020 at 00:35, Morgan Craft <mgan59@...> wrote:

I just went through this process of setting up markdown-linters, so I'm
familiar.

The community around the tooling is great, vscode plugins and
github-actions all have adopted common-mark. Think the common-mark spec is
working with the eco-system of various open-source parsers to get alignment
and it is happening. They have an active community on github and their
talk
<https://talk.commonmark.org/>.

I'm wondering whether we should add a task to our wishlist "Add git
commithook to check for Common Markdown compliance"?

For us, there are github-actions we can configure so our PRS have a
check, this makes the most sense. Locally, we could setup a github hook
that runs a local-cli command -- there would be some setup work there that
varies depending on your platform and tooling.

Cheers,
M





On Sun, May 24, 2020 at 1:40 AM Cameron Shorter <cameron.shorter@...
wrote:

There are multiple variants of Markdown, and I've recently come across
https://commonmark.org/ which attempts to provide an unambiguous
definition
of markdown.
I admire their goals and it appears they have attracted a strong
community.
They aim to achieve interoperability between different markdown
implementations (probably by limiting specific extensions or
interpretations).
For a base project like ours, I'd expect that it would be in our best
interests to align with the Common Markdown format.
Do others have experience with Common Markdown?
Do you have opinions on why we should or should not adopt it?
I'm wondering whether we should add a task to our wishlist "Add git
commit
hook to check for Common Markdown compliance"?

--
Cameron Shorter
Technical Writer at Google

M +61 (0) 419 142 254





--
Cameron Shorter
Technical Writer at Google

M +61 (0) 419 142 254

Re: Should/could we standardize on Common Markdown?

Morgan Craft
 

I just went through this process of setting up markdown-linters, so I'm
familiar.

The community around the tooling is great, vscode plugins and
github-actions all have adopted common-mark. Think the common-mark spec is
working with the eco-system of various open-source parsers to get alignment
and it is happening. They have an active community on github and their talk
<https://talk.commonmark.org/>.

I'm wondering whether we should add a task to our wishlist "Add git
commithook to check for Common Markdown compliance"?

For us, there are github-actions we can configure so our PRS have a
check, this makes the most sense. Locally, we could setup a github hook
that runs a local-cli command -- there would be some setup work there that
varies depending on your platform and tooling.

Cheers,
M





On Sun, May 24, 2020 at 1:40 AM Cameron Shorter <cameron.shorter@...>
wrote:

There are multiple variants of Markdown, and I've recently come across
https://commonmark.org/ which attempts to provide an unambiguous
definition
of markdown.
I admire their goals and it appears they have attracted a strong community.
They aim to achieve interoperability between different markdown
implementations (probably by limiting specific extensions or
interpretations).
For a base project like ours, I'd expect that it would be in our best
interests to align with the Common Markdown format.
Do others have experience with Common Markdown?
Do you have opinions on why we should or should not adopt it?
I'm wondering whether we should add a task to our wishlist "Add git commit
hook to check for Common Markdown compliance"?

--
Cameron Shorter
Technical Writer at Google

M +61 (0) 419 142 254



Should/could we standardize on Common Markdown?

Cameron Shorter
 

There are multiple variants of Markdown, and I've recently come across
https://commonmark.org/ which attempts to provide an unambiguous definition
of markdown.
I admire their goals and it appears they have attracted a strong community.
They aim to achieve interoperability between different markdown
implementations (probably by limiting specific extensions or
interpretations).
For a base project like ours, I'd expect that it would be in our best
interests to align with the Common Markdown format.
Do others have experience with Common Markdown?
Do you have opinions on why we should or should not adopt it?
I'm wondering whether we should add a task to our wishlist "Add git commit
hook to check for Common Markdown compliance"?

--
Cameron Shorter
Technical Writer at Google

M +61 (0) 419 142 254

Re: Baselining our Project Steering Committee

Jared Morgan
 

There do appear to be some dormant members on this list.

It is probably a good time to make this accurate and do a grammar lint over
the file.

I'll do the linting and then we can add the names to the PR before merging.

Does that sound like a good plan?

Jared Morgan
M: +61413005479
Twitter <http://twitter.com/!#/jaredmorgs> | Facebook
<http://facebook.com/jaredmorgs> | GitHub
<https://www.github.com/jaredmorgs>




On Thu, 21 May 2020 at 08:05, Cameron Shorter via groups.io <shortcam=
google.com@groups.io> wrote:

We have been talking about setting up an OpenCollective account which could
be used to sponsor bounty tasks.
To add some rigour to our decision making, I'll reach out to existing PSC
members individually and see if they wish to continue being involved.
The process we use (which I've copied from other open source projects) is
here:

https://github.com/thegooddocsproject/governance/blob/master/ProjectSteeringCommittee.md


--
Cameron Shorter,
Technical Writer, ChromeOS Platforms



Re: Open Collective

Jared Morgan
 

I created an account just then as well.

https://opencollective.com/jaredmorgs

Jared Morgan
M: +61413005479
Twitter <http://twitter.com/!#/jaredmorgs> | Facebook
<http://facebook.com/jaredmorgs> | GitHub
<https://www.github.com/jaredmorgs>

On Fri, 22 May 2020 at 07:00, Felicity <@flicstar> wrote:

Hi folks,

Erin and I worked this morning to set up The Good Docs on Open
Collective - you can see our page here:
https://opencollective.com/thegooddocsproject/

This means the project can accept donations and (fingers crossed) have
backers and sponsors.

PSC members, if any of you already have an Open Collective account (or
would like to create one) I can add you as joint-administrators of our
organization. Erin and I are currently admins.

Thanks
Felicity



Re: Open Collective

Cameron Shorter
 

Thank you Felicity and Erin,
This is a really productive step forward, and a significant milestone for
our project.
I see that we already have our first donation. Thank you Felicity!

I've created a profile for myself:
https://opencollective.com/cameron-shorter

On Fri, 22 May 2020 at 07:00, Felicity <@flicstar> wrote:

Hi folks,

Erin and I worked this morning to set up The Good Docs on Open
Collective - you can see our page here:
https://opencollective.com/thegooddocsproject/

This means the project can accept donations and (fingers crossed) have
backers and sponsors.

PSC members, if any of you already have an Open Collective account (or
would like to create one) I can add you as joint-administrators of our
organization. Erin and I are currently admins.

Thanks
Felicity



--
Cameron Shorter
Technology Writer at Google
Open Technologies and Geospatial Evangelist

M +61 (0) 419 142 254

Open Collective

Felicity
 

Hi folks,

Erin and I worked this morning to set up The Good Docs on Open
Collective - you can see our page here:
https://opencollective.com/thegooddocsproject/

This means the project can accept donations and (fingers crossed) have
backers and sponsors.

PSC members, if any of you already have an Open Collective account (or
would like to create one) I can add you as joint-administrators of our
organization. Erin and I are currently admins.

Thanks
Felicity

Baselining our Project Steering Committee

Cameron Shorter
 

We have been talking about setting up an OpenCollective account which could
be used to sponsor bounty tasks.
To add some rigour to our decision making, I'll reach out to existing PSC
members individually and see if they wish to continue being involved.
The process we use (which I've copied from other open source projects) is
here:
https://github.com/thegooddocsproject/governance/blob/master/ProjectSteeringCommittee.md


--
Cameron Shorter,
Technical Writer, ChromeOS Platforms

Re: Proposal: standing agenda item for the oldest PR

Erin McKean
 

I linked in the oldest one already ... if we cherry-pick we'll never close
things 😂

On Tue, May 19, 2020 at 4:20 PM Cameron Shorter <cameron.shorter@...>
wrote:

Feel free to suggest which issue we review for our first meeting. (Maybe
select an easier one to start with.)
https://github.com/thegooddocsproject/governance/wiki/Weekly-Meetings

On Wed, 20 May 2020 at 08:09, Erin McKean via groups.io <emckean=
google.com@groups.io> wrote:

I've added this as 'Passed' in the decision log:
https://github.com/thegooddocsproject/governance/wiki/Decision-Log-2020

On Tue, May 19, 2020 at 11:24 AM Daniel Beck <daniel@...> wrote:

This proposal has received a few +1s only, so it sounds like we're a go
to
try looking at the oldest PR at the end of the next meeting. 👍

On Thu, May 14, 2020 at 12:49 PM Jared Morgan <
@jaredmorgs>
wrote:

(to the group this time...)

+1 to this idea. It will keep the PRs moving forward even if it is
slowly.

Jared Morgan
M: +61413005479 <+61%20413%20005%20479> <+61%20413%20005%20479>
Twitter <http://twitter.com/!#/jaredmorgs> | Facebook
<http://facebook.com/jaredmorgs> | GitHub
<https://www.github.com/jaredmorgs>




On Thu, 14 May 2020 at 08:20, Daniel Beck <daniel@...> wrote:

Hi folks,

In today's meeting, we talked a bit about improving the review and
merge
process for the project. I proposed a standing agenda item for the
weekly
call: the Oldest PR.

Here's the idea: the last item on the agenda for each meeting is
always
the
oldest open PR in the queue. Ideally, the link to the PR will be
included
in the agenda or calendar invite. Near the end of the meeting, the
group
takes a few minutes to identify a next step toward merging or
closing
the
PR.

For another project I work on, we have this agenda item and it works
well
at inching old PRs to conclusions. The advantage is that it
dedicates
time
to resolving administrative issues (e.g., assigning a reviewer) or
discussing substantive questions (i.e., do we really want this
change?).
The disadvantage is confronting the self-inflicted shame of seeing
how
long
you've put off that PR.

If approved by Tuesday, May 19, then the current oldest PR could go
on
the
agenda for the next meeting scheduled for Wednesday, May 20. I
welcome
your feedback and votes on the matter. :-)

Daniel







--
Erin McKean | Docs Advocacy Program Manager, Open Source Programs Office |
emckean@... | she/her



--
Cameron Shorter
Technology Writer at Google
Open Technologies and Geospatial Evangelist

M +61 (0) 419 142 254 <+61%20419%20142%20254>



--
Erin McKean | Docs Advocacy Program Manager, Open Source Programs Office |
emckean@... | she/her

Re: Proposal: standing agenda item for the oldest PR

Cameron Shorter
 

Feel free to suggest which issue we review for our first meeting. (Maybe
select an easier one to start with.)
https://github.com/thegooddocsproject/governance/wiki/Weekly-Meetings

On Wed, 20 May 2020 at 08:09, Erin McKean via groups.io <emckean=
google.com@groups.io> wrote:

I've added this as 'Passed' in the decision log:
https://github.com/thegooddocsproject/governance/wiki/Decision-Log-2020

On Tue, May 19, 2020 at 11:24 AM Daniel Beck <daniel@...> wrote:

This proposal has received a few +1s only, so it sounds like we're a go
to
try looking at the oldest PR at the end of the next meeting. 👍

On Thu, May 14, 2020 at 12:49 PM Jared Morgan <@jaredmorgs

wrote:

(to the group this time...)

+1 to this idea. It will keep the PRs moving forward even if it is
slowly.

Jared Morgan
M: +61413005479 <+61%20413%20005%20479>
Twitter <http://twitter.com/!#/jaredmorgs> | Facebook
<http://facebook.com/jaredmorgs> | GitHub
<https://www.github.com/jaredmorgs>




On Thu, 14 May 2020 at 08:20, Daniel Beck <daniel@...> wrote:

Hi folks,

In today's meeting, we talked a bit about improving the review and
merge
process for the project. I proposed a standing agenda item for the
weekly
call: the Oldest PR.

Here's the idea: the last item on the agenda for each meeting is
always
the
oldest open PR in the queue. Ideally, the link to the PR will be
included
in the agenda or calendar invite. Near the end of the meeting, the
group
takes a few minutes to identify a next step toward merging or closing
the
PR.

For another project I work on, we have this agenda item and it works
well
at inching old PRs to conclusions. The advantage is that it dedicates
time
to resolving administrative issues (e.g., assigning a reviewer) or
discussing substantive questions (i.e., do we really want this
change?).
The disadvantage is confronting the self-inflicted shame of seeing
how
long
you've put off that PR.

If approved by Tuesday, May 19, then the current oldest PR could go
on
the
agenda for the next meeting scheduled for Wednesday, May 20. I
welcome
your feedback and votes on the matter. :-)

Daniel







--
Erin McKean | Docs Advocacy Program Manager, Open Source Programs Office |
emckean@... | she/her



--
Cameron Shorter
Technology Writer at Google
Open Technologies and Geospatial Evangelist

M +61 (0) 419 142 254

Re: Proposal: Put weekly meeting agenda in wiki

Erin McKean
 

Thanks! I've added this to the decision log (
https://github.com/thegooddocsproject/governance/wiki/Decision-Log-2020)
and the weekly meeting page is now here:
https://github.com/thegooddocsproject/governance/wiki/Weekly-Meetings

On Sun, May 17, 2020 at 9:05 PM Clarence Cromwell <
clarencewcromwell@...> wrote:

+1 for putting the agenda on a wiki.

On Thu, May 14, 2020 at 2:42 PM Erin McKean via groups.io <emckean=
google.com@groups.io> wrote:

Right now Cameron is doing the heavy lifting of setting & sending the
meeting agendas in email and in the meeting invite. (Thank you!)

However, this puts the burden on one person, and it means that people
already have to be on the email list & the calendar invite to see the
agenda.

I propose we create a "Meeting Agenda" page on our wiki (
https://github.com/thegooddocsproject/governance/wiki) and put the
meeting
agendas there, with info on how to join the meetings and a cutoff time for
new agenda items. (This will also serve as a place to put notes, if folks
are so inclined. :) )

Thoughts?

Thanks!

Erin

--
Erin McKean | Docs Advocacy Program Manager, Open Source Programs Office |
emckean@... | she/her



--
Erin McKean | Docs Advocacy Program Manager, Open Source Programs Office |
emckean@... | she/her