[aerogear-dev] [feedhenry-dev] Docs process

[Jason Madigan]

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

[image: Inline image 1]

On Wed, Jan 31, 2018 at 2:17 PM, David Martin <davmarti at redhat.com> 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"
> https://issues.jboss.org/browse/AEROGEAR-1917
>
> 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 <davmarti at redhat.com> 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"
>> https://issues.jboss.org/browse/AEROGEAR-1917
>>
>> 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 <pwright at redhat.com> 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/mi
>>> nishift-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
> feedhenry-dev at redhat.com
> https://www.redhat.com/mailman/listinfo/feedhenry-dev
>
>


-- 
Jason Madigan
Engineering Manager, Red Hat Mobile
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/aerogear-dev/attachments/20180131/31d12cb5/attachment-0001.html 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Screen Shot 2018-01-31 at 14.29.19.png
Type: image/png
Size: 75657 bytes
Desc: not available
Url : http://lists.jboss.org/pipermail/aerogear-dev/attachments/20180131/31d12cb5/attachment-0001.png