[aerogear-dev] AeroGear Android Root Document

[Daniel Passos]

Well, That is what we have today and what we want to follow
 <#>Android Documentations <#> Root document

A documentation explain how to build lib and app
 <#>README

A link for root document and add specific things for conf/run app
 <#>Usage Guide

For each feature we have a document explaining how to use it on the site.
We don’t add any explanation of how to use a feature in the README
 <#>Cookbook

We have only one app to show for community see how to our feature works. We
have one activity per usage guide
 <#> Feature table

I love corinne idea for put table feature on README but I like to move it
for ag lib instead cookbook


On Fri, Dec 13, 2013 at 12:33 PM, Daniel Passos <daniel at passos.me> wrote:

> On Tue, Dec 10, 2013 at 6:00 AM, Corinne Krych <corinnekrych at gmail.com>
> wrote:
>
> Hello Daniel
>>
>> I really buy into your idea.
>> We definitively need more consistent documentation on AeroGear features
>> with concrete and simple exemple (like we started in cookbook).
>>
> The idea is clean up our documentation, write a UNIQUE document explaining
> how to build our lib and apps. Looks like ActionBarSherlock<http://actionbarsherlock.com/usage.html>
>
>    - Prereq
>    - Build
>    - Usage
>
> In all README we will link for this document (on ag.org) and add specific
> things for the app
>
> Let's refactor our documentation together and meake suure we go in the
>> same direction.
>> See Hylke thread on it [1]. As suggested by Hylke, let's group our
>> documentation per category/features: core, push, security, offline/sync. We
>> could have a general description of what the features is, some link to
>> specs etc..
>>
> +1 for reorganize this
>
> Then the sample part. Each sample/recipe(from cookbook) should be well
>> documented and follow a similar template like you gist shown it. I've done
>> similar with iOS-cookbook. One central readme [1] which list all recipes.
>> Each recipes [2] has is own documentation following the same template. We
>> ca work on unifying the template. I like prerequisites section,
>> install/build section common to both, you miss a short description of the
>> app and some ui flow with pictures would be nice and then a last sec ion we
>> we explain the main fatures we want ot demo.
>>
> The root document is not to explain how to use our features. It’s for
> explain how to build our libs and apps.
>
> We don’t have one central README and other specific for cookbook looks
> like iOS, because for Android we have only one cookbook app. This
> application has all our features. For each feature we have one activity
> (screen). This makes the explanation very simple and focus on this feature.
> Each activity (screens) explain one feature and each feature has a usage
> guide on the ag.org ( <http://aerogear.org/docs/guides/aerogear-android/>
> http://aerogear.org/docs/guides/aerogear-android/))
>
> A couple of questions on implementation though:
>> - Instead of just having links to cookbook, how can we embed in asciidoc
>> or markdown? the sample documentation should belong to the cookbook repo.
>> - How are we going to publish read me info from cookbook into
>> aerogear.org repo? a build or some sort of automation will be good.
>>
>  I think those questions have been answered above.
>
>> ++
>> Corinne
>> [1]
>> http://aerogear-dev.1069024.n5.nabble.com/aerogear-dev-Website-restructure-td5246.html
>> [1]
>> https://github.com/corinnekrych/aerogear-ios-cookbook/blob/master/README.md
>> [2]
>> https://github.com/corinnekrych/aerogear-ios-cookbook/blob/master/Xmas/Xmas.md
>>
>> On Dec 9, 2013, at 11:20 PM, Daniel Passos <daniel at passos.me> wrote:
>>
>> > Summers and I tossed around the idea last week to create a 'root
>> document' how to build AeroGear android lib and apps.
>> >
>> > The idea is write a simple document that looks like ActionBar Sherlock
>> doc instead of having a huge doc with lots of repeated setup, have a setup
>> docs which branch from there
>> >
>> > Publish it on aerogear.org and link all others (like README) with it
>> >
>> > My draft for it is here:
>> https://gist.github.com/danielpassos/4b4e694c1c71473b4f59
>> >
>> > wdyt?
>> >
>> > --  Daniel Passos
>> >
>> > _______________________________________________
>> > aerogear-dev mailing list
>> > aerogear-dev at lists.jboss.org
>> > https://lists.jboss.org/mailman/listinfo/aerogear-dev
>>
>>
>> _______________________________________________
>> aerogear-dev mailing list
>> aerogear-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/aerogear-dev/attachments/20131213/4a93e0e9/attachment-0001.html