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@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/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)