<div dir="ltr"><div class="markdown-here-wrapper" id="markdown-here-wrapper-609581" style><p style="margin:1.2em 0px!important">On Tue, Dec 10, 2013 at 6:00 AM, Corinne Krych <<a href="mailto:corinnekrych@gmail.com" target="_blank">corinnekrych@gmail.com</a>> wrote:</p>
<p style="margin:1.2em 0px!important"></p><div class="markdown-here-exclude"><p></p><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
Hello Daniel<br>
<br>
I really buy into your idea.<br>
We definitively need more consistent documentation on AeroGear features with concrete and simple exemple (like we started in cookbook).<br></blockquote><p></p></div><p style="margin:1.2em 0px!important"></p>
<p style="margin:1.2em 0px!important">The idea is clean up our documentation, write a UNIQUE document explaining how to build our lib and apps. Looks like <a href="http://actionbarsherlock.com/usage.html">ActionBarSherlock</a></p>
<ul style="margin:1.2em 0px;padding-left:2em">
<li style="margin:0.5em 0px">Prereq</li>
<li style="margin:0.5em 0px">Build</li>
<li style="margin:0.5em 0px">Usage</li>
</ul>
<p style="margin:1.2em 0px!important">In all README we will link for this document (on <a href="http://ag.org">ag.org</a>) and add specific things for the app</p>
<p style="margin:1.2em 0px!important"></p><div class="markdown-here-exclude"><p></p><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
Let's refactor our documentation together and meake suure we go in the same direction.<br>
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..<br>
</blockquote><p></p></div><p style="margin:1.2em 0px!important"></p>
<p style="margin:1.2em 0px!important">+1 for reorganize this</p>
<p style="margin:1.2em 0px!important"></p><div class="markdown-here-exclude"><p></p><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
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.<br>
</blockquote><p></p></div><p style="margin:1.2em 0px!important"></p>
<p style="margin:1.2em 0px!important">The root document is not to explain how to use our features. It’s for explain how to build our libs and apps. </p>
<p style="margin:1.2em 0px!important">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 <a href="http://ag.org">ag.org</a> (<a href="http://aerogear.org/docs/guides/aerogear-android/"></a><a href="http://aerogear.org/docs/guides/aerogear-android/">http://aerogear.org/docs/guides/aerogear-android/</a>))</p>
<p style="margin:1.2em 0px!important"></p><div class="markdown-here-exclude"><p></p><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
A couple of questions on implementation though:<br>
- Instead of just having links to cookbook, how can we embed in asciidoc or markdown? the sample documentation should belong to the cookbook repo.<br>
- How are we going to publish read me info from cookbook into <a href="http://aerogear.org" target="_blank">aerogear.org</a> repo? a build or some sort of automation will be good.<br></blockquote><p></p></div><p style="margin:1.2em 0px!important">
</p>
<p style="margin:1.2em 0px!important">I think those questions have been answered above.</p><div class="markdown-here-exclude"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
++<br>
Corinne<br>
[1] <a href="http://aerogear-dev.1069024.n5.nabble.com/aerogear-dev-Website-restructure-td5246.html" target="_blank">http://aerogear-dev.1069024.n5.nabble.com/aerogear-dev-Website-restructure-td5246.html</a><br>
[1] <a href="https://github.com/corinnekrych/aerogear-ios-cookbook/blob/master/README.md" target="_blank">https://github.com/corinnekrych/aerogear-ios-cookbook/blob/master/README.md</a><br>
[2] <a href="https://github.com/corinnekrych/aerogear-ios-cookbook/blob/master/Xmas/Xmas.md" target="_blank">https://github.com/corinnekrych/aerogear-ios-cookbook/blob/master/Xmas/Xmas.md</a><br>
<div><div class="h5"><br>
On Dec 9, 2013, at 11:20 PM, Daniel Passos <<a href="mailto:daniel@passos.me">daniel@passos.me</a>> wrote:<br>
<br>
> Summers and I tossed around the idea last week to create a 'root document' how to build AeroGear android lib and apps.<br>
><br>
> 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<br>
><br>
> Publish it on <a href="http://aerogear.org" target="_blank">aerogear.org</a> and link all others (like README) with it<br>
><br>
> My draft for it is here: <a href="https://gist.github.com/danielpassos/4b4e694c1c71473b4f59" target="_blank">https://gist.github.com/danielpassos/4b4e694c1c71473b4f59</a><br>
><br>
> wdyt?<br>
><br>
> -- Daniel Passos<br>
><br>
</div></div>> _______________________________________________<br>
> aerogear-dev mailing list<br>
> <a href="mailto:aerogear-dev@lists.jboss.org">aerogear-dev@lists.jboss.org</a><br>
> <a href="https://lists.jboss.org/mailman/listinfo/aerogear-dev" target="_blank">https://lists.jboss.org/mailman/listinfo/aerogear-dev</a><br>
<br>
<br>
_______________________________________________<br>
aerogear-dev mailing list<br>
<a href="mailto:aerogear-dev@lists.jboss.org">aerogear-dev@lists.jboss.org</a><br>
<a href="https://lists.jboss.org/mailman/listinfo/aerogear-dev" target="_blank">https://lists.jboss.org/mailman/listinfo/aerogear-dev</a><br>
</blockquote><p></p></div><p style="margin:1.2em 0px!important"></p>
</div></div>