[aerogear-dev] 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"
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)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/aerogear-dev/attachments/20180131/5e48f2a7/attachment.html