[aerogear-dev] Website restructure

[Corinne Krych]

Interesting link Karel, thanks for sharing. I’ll have a on look how to include cookbook spnippet in arg.org. 
++
Corinne
On 27 Jan 2014, at 13:25, Karel Piwko <kpiwko at redhat.com> wrote:

> On Fri, 24 Jan 2014 15:58:27 +0100
> Corinne Krych <corinnekrych at gmail.com> wrote:
> 
>> Hello All,
>> 
>> I’ve being working on sass branch [1], the same branch Erik-Jan did its
>> initial work. Here is more feedback on our site redesign
>> 
>> 1. Example page with each language code snippet
>> It’s a good idea, to show the unified aspect of our libs. Having a short
>> snippet code is great, however it’s not possible to fit the detailed example
>> we alreday have in our documentation. Rather than simplifying and not going
>> into details, I think we could have a main page like [2] which give the
>> definition + each snippet. Below the code snipet I’ve added a link: Read more
>> on Pipes on Android / Pipes on iOS / Paging on Web which points to detailled
>> page.
>> 
>> I think we should keep this documetation. It goes deeper in the sample code
>> as opposed to snippet which is not necessarly complete code. One think that
>> we could do is use code sample extracted from our cookbook recipe. So we can
>> point to the repository for the full app code.
>> 
>> @Hylke Do you have a better idea than just a simple link? I think it’s not
>> visual enough. And what should be the layout of the detailled example page?
>> 
> Asciidoc allows to directly source a snipet from a file. Keeping code snippet on
> a single place in repo and automatically propagated to the documentation
> during page build. We were at least planning to use it on arquillian.org but
> it's imho not at the place atm.
> 
> More details here:
> http://codeextactor.berlios.de/codeextractor.html
> https://groups.google.com/forum/#!topic/asciidoc/v0bofNfTGs4
> 
>> 2. New structure
>> As hylke asked for it, here a proposal, wdyt?
>> _ Core
>> __ Pipe
>> __ Paging
>> __ Store
>> 
>> _ Security
>> __ Authentication
>> __ Encryption
>> 
>> _ Push
>> __ Registration
>> __ Sender 
>> 
>> 3. Refactoring of each documentaiton is needed to fit this structure:
>> How do we want to proceed? One guy is doing the full refactor of doc (poor
>> guy) or we split it into a bunch of JIRAs? Maybe as @qmx suggested once we’ve
>> go the structure we could merge the PR and find a way to progressively
>> refactor. 
>> 
>> 4. markdown or asciidoc ?
>> It’s a great opportunity to unify our doc. asciidoc offers great plugins. For
>> example page, we use tab plugin.
>> 
>> 5. Dracula theme vs White theme
>> If you uncomment [3] you can have a white theme. A shame that with Dracula
>> theme we loose the AeroGear blue and orange logo... @Hylke for the dracula
>> theme we need AG logo in each of the 3 colors.
>> 
>> 5. Menu
>> @Hylke you said you want to remove the actual menu, but what do you propose
>> to navigate between topic: Core/Security/Push/Sync
>> 
>> 6. Mobile site
>> New design need to be responsive. Actual CSS are not any more. But we can fix
>> them ;)
>> 
>> ++
>> Corinne
>> [1] https://github.com/aerogear/aerogear.org/tree/sass
>> [2] http://localhost:4000/docs/guides/new/index/
>> [3] https://github.com/aerogear/aerogear.org/blob/sass/sass/main.sass#L117
>> 
>> On 22 Jan 2014, at 14:13, Hylke Bons <hbons at redhat.com> wrote:
>> 
>>> On 22/01/2014 13:00, Corinne Krych wrote:
>>>> I like the original idea in the mockup (core/Security/Push), maybe we can
>>>> introduce sub-section like:
>>>> - Core (pipe - paging / store)
>>>> - Security(authentication - OTP - OAuth2 / encryption /
>>>> - Push (push registration / sender api / UPS - Simple Push)
>>>> - Sync
>>>> 
>>>> wdyt?
>>>> ++
>>>> Corinne
>>> 
>>> Yes, exactly that! :)
>>> I'm doing that as we speak, but I'm not sure what all the (useful) 
>>> classes are.
>>> 
>>> Hylke
>>> 
>>> 
>>> 
>>> 
>>>> On 22 Jan 2014, at 13:03, Karel Piwko <kpiwko at redhat.com> wrote:
>>>> 
>>>>> On Tue, 21 Jan 2014 12:43:39 +0000
>>>>> Hylke Bons <hbons at redhat.com> wrote:
>>>>> 
>>>>>> On 20/01/2014 17:31, Corinne Krych wrote:
>>>>>>>> On Mon, Jan 20, 2014 at 12:35 PM, Karel Piwko <kpiwko at redhat.com>
>>>>>>>> wrote: Looks good!
>>>>>>>> +1 I like the dracula theme !
>>>>>>>> 
>>>>>>>> Apart for platform related code (JavaScript, Objective-C, Java), are
>>>>>>>> there any plans to support platform related text?
>>>>>>>> 
>>>>>>>> E.g. pipes on Aerogear can be used within FragmentActivity, which is
>>>>>>>> valid for Android only; Javadoc is not related to iOS, etc. That's
>>>>>>>> basically a merge of our guides into a one per feature with
>>>>>>>> information covering all the platforms.
>>>>>> Is there a list of the most important features/classes/objects that I
>>>>>> can use in the mockup?
>>>>> I'm not aware of any. Trying to compose list of features, I'd go for:
>>>>> 
>>>>> * Push Messages
>>>>> * Pipes
>>>>> * Authentication
>>>>> ** OTP
>>>>> * Crypto
>>>>> 
>>>>> 
>>>>>>>> Which brings me to and idea of global platform switch. User/reader can
>>>>>>>> switch platform once and all code snippets and platform related blocks
>>>>>>>> are automatically selected. Can also be session based and affect all
>>>>>>>> pages user visits.
>>>>>> Interesting idea. :)
>>>>>> 
>>>>>> Hylke
>>>>>> 
>>>>>> _______________________________________________
>>>>>> 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
>>>> 
>>>> _______________________________________________
>>>> 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
>> 
>> 
>> _______________________________________________
>> 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