[aerogear-dev] Website restructure

Corinne Krych corinnekrych at gmail.com
Fri Jan 24 09:58:27 EST 2014


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?

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




More information about the aerogear-dev mailing list