<div dir="ltr">Lets try that again...<div><br></div><div><br></div><div><div><br></div><div>@Paul, how about this approach when creating docs tasks in Epics.</div><div><br></div><div>* Identify the 'action' that is the focus of the docs task, and include that in the jira title/description.</div><div><br></div><div>So taking this task as an example,</div><div>"Document how the Single Auth Provider works and is configured"</div><div><a href="https://issues.jboss.org/browse/AEROGEAR-1917">https://issues.jboss.org/browse/AEROGEAR-1917</a></div><div><br></div><div>this could be rephrased to something like:</div><div>"Document how an OpenShift user can be given access to a Mobile Service".</div><div>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).</div><div>But it also hints at there being a goal for that doc.</div><div>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</div></div><div><br></div><div><br></div><div>Better?</div></div><div class="gmail_extra"><br><div class="gmail_quote">On 31 January 2018 at 14:11, David Martin <span dir="ltr"><<a href="mailto:davmarti@redhat.com" target="_blank">davmarti@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div style="font-size:12.8px;background-color:rgb(34,34,34)">Sending on list</div><span class=""><div style="font-size:12.8px;background-color:rgb(34,34,34)"><br></div><div style="font-size:12.8px;background-color:rgb(34,34,34)">@Paul, how about this approach when creating docs tasks in Epics.</div><div style="font-size:12.8px;background-color:rgb(34,34,34)"><br></div><div style="font-size:12.8px;background-color:rgb(34,34,34)">* Identify the 'action' that is the focus of the docs task, and include that in the jira title/description.</div><div style="font-size:12.8px;background-color:rgb(34,34,34)"><br></div><div style="font-size:12.8px;background-color:rgb(34,34,34)">So taking this task as an example,</div><div style="font-size:12.8px;background-color:rgb(34,34,34)">"Document how the Single Auth Provider works and is configured"<br></div><div style="font-size:12.8px;background-color:rgb(34,34,34)"><a href="https://issues.jboss.org/browse/AEROGEAR-1917" target="_blank">https://issues.jboss.org/brows<wbr>e/AEROGEAR-1917</a><br></div><div style="font-size:12.8px;background-color:rgb(34,34,34)"><br></div><div style="font-size:12.8px;background-color:rgb(34,34,34)">this could be rephrased to something like:</div><div style="font-size:12.8px;background-color:rgb(34,34,34)">"Document how an OpenShift user can be given access to a Mobile Service".</div><div style="font-size:12.8px;background-color:rgb(34,34,34)">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).</div><div style="font-size:12.8px;background-color:rgb(34,34,34)">But it also hints at there being a goal for that doc.</div><div style="font-size:12.8px;background-color:rgb(34,34,34)">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</div><div class="m_-1122528404204121358gmail-yj6qo m_-1122528404204121358gmail-ajU" style="font-size:12.8px;background-color:rgb(34,34,34)"></div></span></div><div class="gmail_extra"><br><div class="gmail_quote"><span class="">On 31 January 2018 at 12:09, Paul Wright <span dir="ltr"><<a href="mailto:pwright@redhat.com" target="_blank">pwright@redhat.com</a>></span> wrote:<br></span><div><div class="h5"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hi David,<br>
<br>
Preamble: this is still a bit nebulous, but might become a proposal for a docs process:<br>
<br>
I've got a few examples of mobile.next docs items, and here's the issue<br>
<br>
1. Eng want to write specific pieces required by an epic<br>
<br>
2. Docs want to publish end-user docs with context, fitting into an overall flow/user story/structure<br>
<br>
An example is <a href="https://github.com/aerogear/mobile-docs/pull/7/files" rel="noreferrer" target="_blank">https://github.com/aerogear/mo<wbr>bile-docs/pull/7/files</a><br>
<br>
I'm struggling to find context for this piece, but at the same time the guys want to close out the epic.<br>
<br>
Another example is the readme at <a href="https://github.com/aerogear/minishift-mobilecore-addon" rel="noreferrer" target="_blank">https://github.com/aerogear/mi<wbr>nishift-mobilecore-addon</a><br>
<br>
(which will land in mobile-docs as <a href="https://github.com/finp/mobile-docs/blob/AEROGEAR-1982/getting-started/minishift_install.adoc" rel="noreferrer" target="_blank">https://github.com/finp/mobile<wbr>-docs/blob/AEROGEAR-1982/getti<wbr>ng-started/minishift_install.<wbr>adoc</a>)<br>
<br>
Given this:<br>
<br>
* I don't want to block eng<br>
<br>
* I don't want to 'light' review material<br>
<br>
* some docs have a life outside of mobile-docs repo<br>
<br>
I'm thinking of the following procedure:<br>
<br>
1. Write your docs in the repo of choice (and merge, eg finishing epic)<br>
<br>
2. I'll create a placeholder in mobile-docs for that doc , eg<br>
<br>
mobile-docs/services/metrics-s<wbr>ingle-auth-provider.adoc<br>
<br>
with a reference to the source material (in code repo)<br>
<br>
3. Create a follow up task to 'create upstream doc and reconcile with code repo'<br>
<br>
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.<br>
<br>
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 <a href="https://github.com/aerogear/mobile-docs/pull/7/files" rel="noreferrer" target="_blank">https://github.com/aerogear/mo<wbr>bile-docs/pull/7/files</a><br>
<br>
<br>
WDYT?<span class="m_-1122528404204121358HOEnZb"><font color="#888888"><br>
<br>
Paul<br>
<br>
<br>
<br>
<br>
-- <br>
Paul Wright<br>
Mobile Docs (github: finp)<br>
<br>
</font></span></blockquote></div></div></div><br><br clear="all"><span class=""><div><br></div>-- <br><div class="m_-1122528404204121358gmail_signature" data-smartmail="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div><div dir="ltr">David Martin<div>Red Hat Mobile</div><div>Twitter: <span style="font-size:12.8px">@irldavem</span></div><div><span style="font-size:12.8px">IRC: @irldavem (#aerogear)</span></div></div></div></div></div></div></div>
</span></div>
</blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature" data-smartmail="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div><div dir="ltr">David Martin<div>Red Hat Mobile</div><div>Twitter: <span style="font-size:12.8px">@irldavem</span></div><div><span style="font-size:12.8px">IRC: @irldavem (#aerogear)</span></div></div></div></div></div></div></div>
</div>