Re: Docs process

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

Re: Docs process

David Martin
Sending on list

@Paul, how about this approach when creating docs tasks in Epics.

* Identify the 'action' that is the focus of the docs task, and include that in the jira title/description.

So taking this task as an example,
"Document how the Single Auth Provider works and is configured"

this could be rephrased to something like:
"Document how an OpenShift user can be given access to a Mobile Service".
This would contain a lot of similar content to what Steven has already written (as it explains how the openshift roles for that namespace give/restrict access to a service via the oauth proxy).
But it also hints at there being a goal for that doc.
Having this info in the task when it is started could help influence and shape how the doc is written so it is closer to what you want at PR time

On 31 January 2018 at 12:09, Paul Wright <[hidden email]> wrote:
Hi David,

Preamble: this is still a bit nebulous, but might become a proposal for a docs process:

I've got a few examples of mobile.next docs items, and here's the issue

1. Eng want to write specific pieces required by an epic

2. Docs want to publish  end-user docs with context, fitting into an overall flow/user story/structure

An example is https://github.com/aerogear/mobile-docs/pull/7/files

I'm struggling to find context for this piece, but at the same time the guys want to close out the epic.

Another example is the readme at https://github.com/aerogear/minishift-mobilecore-addon

(which will land in mobile-docs as https://github.com/finp/mobile-docs/blob/AEROGEAR-1982/getting-started/minishift_install.adoc)

Given this:

* I don't want to block eng

* I don't want to 'light' review material

* some docs have a life outside of mobile-docs repo

I'm thinking of the following procedure:

1. Write your docs in the repo of choice (and merge, eg finishing epic)

2. I'll create a placeholder in mobile-docs for that doc , eg

mobile-docs/services/metrics-single-auth-provider.adoc

with a reference to the source material (in code repo)

3. Create a follow up task to 'create upstream doc and reconcile with code repo'

The idea being that eventually, the doc in the code repo is equivalent to mobile-docs repo, but that becomes async, not depending on me to sort everything out to satisfy some epic closure pressure.

Obviously, this is not ideal, because developer has moved on by the time I'm reviewing doc, but not everything will require as much context filling as https://github.com/aerogear/mobile-docs/pull/7/files


WDYT?

Paul




--
Paul Wright
Mobile Docs (github: finp)




--
David Martin
Red Hat Mobile
Twitter: @irldavem
IRC: @irldavem (#aerogear)

_______________________________________________
feedhenry-dev mailing list
[hidden email]
https://www.redhat.com/mailman/listinfo/feedhenry-dev
Reply | Threaded
Open this post in threaded view
|

Re: Docs process

David Martin
Lets try that again...



@Paul, how about this approach when creating docs tasks in Epics.

* Identify the 'action' that is the focus of the docs task, and include that in the jira title/description.

So taking this task as an example,
"Document how the Single Auth Provider works and is configured"

this could be rephrased to something like:
"Document how an OpenShift user can be given access to a Mobile Service".
This would contain a lot of similar content to what Steven has already written (as it explains how the openshift roles for that namespace give/restrict access to a service via the oauth proxy).
But it also hints at there being a goal for that doc.
Having this info in the task when it is started could help influence and shape how the doc is written so it is closer to what you want at PR time


Better?

On 31 January 2018 at 14:11, David Martin <[hidden email]> wrote:
Sending on list

@Paul, how about this approach when creating docs tasks in Epics.

* Identify the 'action' that is the focus of the docs task, and include that in the jira title/description.

So taking this task as an example,
"Document how the Single Auth Provider works and is configured"

this could be rephrased to something like:
"Document how an OpenShift user can be given access to a Mobile Service".
This would contain a lot of similar content to what Steven has already written (as it explains how the openshift roles for that namespace give/restrict access to a service via the oauth proxy).
But it also hints at there being a goal for that doc.
Having this info in the task when it is started could help influence and shape how the doc is written so it is closer to what you want at PR time

On 31 January 2018 at 12:09, Paul Wright <[hidden email]> wrote:
Hi David,

Preamble: this is still a bit nebulous, but might become a proposal for a docs process:

I've got a few examples of mobile.next docs items, and here's the issue

1. Eng want to write specific pieces required by an epic

2. Docs want to publish  end-user docs with context, fitting into an overall flow/user story/structure

An example is https://github.com/aerogear/mobile-docs/pull/7/files

I'm struggling to find context for this piece, but at the same time the guys want to close out the epic.

Another example is the readme at https://github.com/aerogear/minishift-mobilecore-addon

(which will land in mobile-docs as https://github.com/finp/mobile-docs/blob/AEROGEAR-1982/getting-started/minishift_install.adoc)

Given this:

* I don't want to block eng

* I don't want to 'light' review material

* some docs have a life outside of mobile-docs repo

I'm thinking of the following procedure:

1. Write your docs in the repo of choice (and merge, eg finishing epic)

2. I'll create a placeholder in mobile-docs for that doc , eg

mobile-docs/services/metrics-single-auth-provider.adoc

with a reference to the source material (in code repo)

3. Create a follow up task to 'create upstream doc and reconcile with code repo'

The idea being that eventually, the doc in the code repo is equivalent to mobile-docs repo, but that becomes async, not depending on me to sort everything out to satisfy some epic closure pressure.

Obviously, this is not ideal, because developer has moved on by the time I'm reviewing doc, but not everything will require as much context filling as https://github.com/aerogear/mobile-docs/pull/7/files


WDYT?

Paul




--
Paul Wright
Mobile Docs (github: finp)




--
David Martin
Red Hat Mobile
Twitter: @irldavem
IRC: @irldavem (#aerogear)



--
David Martin
Red Hat Mobile
Twitter: @irldavem
IRC: @irldavem (#aerogear)

_______________________________________________
feedhenry-dev mailing list
[hidden email]
https://www.redhat.com/mailman/listinfo/feedhenry-dev
Reply | Threaded
Open this post in threaded view
|

Re: Docs process

Jason Madigan
@David - keen to see what your redacted reply was ;)

Inline image 1

On Wed, Jan 31, 2018 at 2:17 PM, David Martin <[hidden email]> wrote:
Lets try that again...



@Paul, how about this approach when creating docs tasks in Epics.

* Identify the 'action' that is the focus of the docs task, and include that in the jira title/description.

So taking this task as an example,
"Document how the Single Auth Provider works and is configured"

this could be rephrased to something like:
"Document how an OpenShift user can be given access to a Mobile Service".
This would contain a lot of similar content to what Steven has already written (as it explains how the openshift roles for that namespace give/restrict access to a service via the oauth proxy).
But it also hints at there being a goal for that doc.
Having this info in the task when it is started could help influence and shape how the doc is written so it is closer to what you want at PR time


Better?

On 31 January 2018 at 14:11, David Martin <[hidden email]> wrote:
Sending on list

@Paul, how about this approach when creating docs tasks in Epics.

* Identify the 'action' that is the focus of the docs task, and include that in the jira title/description.

So taking this task as an example,
"Document how the Single Auth Provider works and is configured"

this could be rephrased to something like:
"Document how an OpenShift user can be given access to a Mobile Service".
This would contain a lot of similar content to what Steven has already written (as it explains how the openshift roles for that namespace give/restrict access to a service via the oauth proxy).
But it also hints at there being a goal for that doc.
Having this info in the task when it is started could help influence and shape how the doc is written so it is closer to what you want at PR time

On 31 January 2018 at 12:09, Paul Wright <[hidden email]> wrote:
Hi David,

Preamble: this is still a bit nebulous, but might become a proposal for a docs process:

I've got a few examples of mobile.next docs items, and here's the issue

1. Eng want to write specific pieces required by an epic

2. Docs want to publish  end-user docs with context, fitting into an overall flow/user story/structure

An example is https://github.com/aerogear/mobile-docs/pull/7/files

I'm struggling to find context for this piece, but at the same time the guys want to close out the epic.

Another example is the readme at https://github.com/aerogear/minishift-mobilecore-addon

(which will land in mobile-docs as https://github.com/finp/mobile-docs/blob/AEROGEAR-1982/getting-started/minishift_install.adoc)

Given this:

* I don't want to block eng

* I don't want to 'light' review material

* some docs have a life outside of mobile-docs repo

I'm thinking of the following procedure:

1. Write your docs in the repo of choice (and merge, eg finishing epic)

2. I'll create a placeholder in mobile-docs for that doc , eg

mobile-docs/services/metrics-single-auth-provider.adoc

with a reference to the source material (in code repo)

3. Create a follow up task to 'create upstream doc and reconcile with code repo'

The idea being that eventually, the doc in the code repo is equivalent to mobile-docs repo, but that becomes async, not depending on me to sort everything out to satisfy some epic closure pressure.

Obviously, this is not ideal, because developer has moved on by the time I'm reviewing doc, but not everything will require as much context filling as https://github.com/aerogear/mobile-docs/pull/7/files


WDYT?

Paul




--
Paul Wright
Mobile Docs (github: finp)




--
David Martin
Red Hat Mobile
Twitter: @irldavem
IRC: @irldavem (#aerogear)



--
David Martin
Red Hat Mobile
Twitter: @irldavem
IRC: @irldavem (#aerogear)

_______________________________________________
feedhenry-dev mailing list
[hidden email]
https://www.redhat.com/mailman/listinfo/feedhenry-dev




--
Jason Madigan
Engineering Manager, Red Hat Mobile

_______________________________________________
feedhenry-dev mailing list
[hidden email]
https://www.redhat.com/mailman/listinfo/feedhenry-dev