[aerogear-dev] SDK API doc

[John Frizelle]

I think some beautiful marriage between stand alone API docs for the deep
documentation and slate for language specific samples examples is the way
to go here.

I actually really like the slate UI & UX and would be very much in favour
of using it (at least at some layer of our docs)...


--
John Frizelle
Chief Architect, Red Hat Mobile
Consulting Engineer

mobile: *+353 87 290 1644 <//+353872901644>*
twitter:* @johnfriz*
skype: *john_frizelle*
mail: *jfrizell at redhat.com <jfrizell at redhat.com>*




On 1 February 2018 at 15:55, Wojciech Trocki <wtrocki at redhat.com> wrote:

> Worth to mention that there is also alternative aproach when all apis are
> available together.
> For example:
>
> https://github.com/lord/slate
>
> On Thu, Feb 1, 2018 at 3:44 PM, Wojciech Trocki <wtrocki at redhat.com>
> wrote:
>
>> Awesome idea to use different tooling.
>>
>> We could generate documentation on release (by tooling) and use state of
>> the art solutions for each platform.
>> Each platform is different and there are different tools available so
>> keeping the format may be hard.
>>
>> There are plenty of projects that give us this out of the box. Just
>> couple examples:
>>
>> https://github.com/realm/jazzy (ios)
>> http://typedoc.org/ (TypeScript - cordova)
>>
>> Another really good idea mentioned above is to avoid extensive code
>> examples in documentation by referencing api docs.
>> We have done that in RainCatcher and it worked really good
>>
>> http://raincatcher.feedhenry.io/docs/#_logging (see logger api
>> documentation)
>>
>> This will help us to avoid our documentation getting out of sync with the
>> actual code.
>> We could host that on github pages for community.
>> I think that it will be hard to get into details on mailing list so we
>> could create proposal for API docs.
>>
>> On Thu, Feb 1, 2018 at 3:32 PM, Paul Wright <pwright at redhat.com> wrote:
>>
>>> Hi,
>>>
>>> There is existing tooling to generate API reference doc for Android and
>>> iOS. I'm thinking we should use that to generate comprehensive API doc for
>>> both platforms (and later for Cordova).
>>>
>>> I believe this gives the best experience to the <platform> developer, on
>>> the basis that, at any one time, they developer is working on a single
>>> platform (and typically a colleague is developing the 'other' platform).
>>> The disadvantages of this approach include the fact that the appearance of
>>> generic docs/android/ios will all be different, but we can put enough
>>> navigation into the html to allow users enter and exit this reference
>>> without too much pain.
>>>
>>> However there is also a requirement to show the cross platform nature of
>>> mobile-next, to demonstrate the generic nature of a particular call. I'd
>>> like to address this, not in the 'full' API docs, but in examples of
>>> typical use cases which might look like
>>>
>>> getSyncClient().list("tasks");
>>>
>>> For more information see <link to android ref docs>
>>>
>>> syncClient.listWithDataId("tasks")
>>>
>>> For more information see <link to ios ref docs>
>>>
>>>
>>> WDYT?
>>>
>>> --
>>> Paul Wright
>>> Mobile Docs (github: finp)
>>>
>>> --
>>> You received this message because you are subscribed to the Google
>>> Groups "Aerogear" group.
>>> To unsubscribe from this group and stop receiving emails from it, send
>>> an email to aerogear+unsubscribe at googlegroups.com.
>>> To post to this group, send email to aerogear at googlegroups.com.
>>> To view this discussion on the web visit https://groups.google.com/d/ms
>>> gid/aerogear/5749d108-985c-250a-422c-27fbaa7c3e91%40redhat.com
>>> <https://groups.google.com/d/msgid/aerogear/5749d108-985c-250a-422c-27fbaa7c3e91%40redhat.com?utm_medium=email&utm_source=footer>
>>> .
>>> For more options, visit https://groups.google.com/d/optout.
>>>
>>
>>
>>
>> --
>>
>> WOJCIECH TROCKI
>>
>> Red Hat Mobile <https://www.redhat.com/>
>>
>> IM: wtrocki
>> <https://red.ht/sig>
>>
>
>
>
> --
>
> WOJCIECH TROCKI
>
> Red Hat Mobile <https://www.redhat.com/>
>
> IM: wtrocki
> <https://red.ht/sig>
>
> --
> You received this message because you are subscribed to the Google Groups
> "Aerogear" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to aerogear+unsubscribe at googlegroups.com.
> To post to this group, send email to aerogear at googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/
> msgid/aerogear/CAO0%2Bn%2BqgokrQtTqd6B1Oab-upe-C5PUvJh0evyJG9Z_LPd1ArQ%
> 40mail.gmail.com
> <https://groups.google.com/d/msgid/aerogear/CAO0%2Bn%2BqgokrQtTqd6B1Oab-upe-C5PUvJh0evyJG9Z_LPd1ArQ%40mail.gmail.com?utm_medium=email&utm_source=footer>
> .
>
> For more options, visit https://groups.google.com/d/optout.
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/aerogear-dev/attachments/20180201/da972e5b/attachment-0001.html 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: logo.png
Type: image/png
Size: 11472 bytes
Desc: not available
Url : http://lists.jboss.org/pipermail/aerogear-dev/attachments/20180201/da972e5b/attachment-0001.png