[aerogear-dev] Website restructure

[Karel Piwko]

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