[aerogear-dev] Website restructure

[Summers Pittman]

On 11/04/2013 10:24 AM, Hylke Bons wrote:
> Hey everyone,
>
> So Jay asked me to look at how the website content is structured and how
> to improve it. Since we have so much content, it gets confusing very
> quickly.
>
> https://raw.github.com/hbons/aerogear-design/master/aerogear-project.png
>
> Here's a mockup of a possible solution. I'm better at explaining things
> in pictures than in words, so please have a look. I'll explain things in
> more detail below.
>
> I've tried to keep every subproject use case based, and explain the use
> case before features. See this as a bigger picture, and don't focus on
> the graphic design too much, it's there to help explain the structure of
> the project, and is not necessarilly a final graphical design in any way
> (though if you like it we can make it work!), but I wanted to show how
> different colour palettes can help explain the project and give a better
> sense of where you are on the website.
>
> I've done a lot of research on the project, but some things may be
> wrong. So your feedback on that would be greatly appreciated. Even after
> spending many months with the project, I still don't fully grasp
> everything (which shows part of the problem).
>
> 1. Naming
> I've split up the project into three main subprojects: "AeroGear Core",
> "AeroGear Push", and "AeroGear Security". These three are the main focus
> and use different icons and colour codings throughout the website to
> guide people. Each subproject has "client" and "server" components.
> Server pieces being appended by "Server Component" and may be standalone
> or an addin to something. Client (API) pieces follow "Project.Namespace"
> format. This way, there's never any confusion about what we're talking
> about in the documentation and marketing materials.
>
> 2. Documentation
> Splitting up documentation. "documentation" can be a broad term. I
> suggest splitting it up in three parts to easily find what you're
> looking for: "Setting up" (downloading and boatstrapping a dev
> environment), "Examples" (how to use the API in your environment to get
> started), "API Documentation" (speaks for itself), and "Tutorials"
> (setting up more complex environments and API usage). This covers most
> of the documentation that is currently on aerogear.org and will make it
> a lot easier to browse.
>
> 3. Coding languages
> Where the API is unified across all platforms (hopefully most of it), we
> can generalise example docs, and show a switcher for code blocks that
> shows how to do a certain thing in a particular language using the
> AeroGear API.
>
> 4. 1:1 mappings
> I'd like to see the iOS, Android and Javscript APIs be self-contained
> things that you can just drop in and use, with 1:1 mappings (what you
> get on Android for a (sub)project, is what you get on iOS). There could
> be technical reasons why these things are split up the way they are now,
> let me know if so. I could be totally wrong on this too.
>
> Missing pieces:
> - Where do we fit in Cordova?
> - AeroGear Auth, Controller?
AeroGear Controller is deprecated so that one is easy :)
>
> These are things I'm not sure yet how they would fit in the proposed scheme.
>
> I think this is a step in the right direction, and I really hope it is
> helpful. Let's iterate on this. Let me know what you think and how we
> can improve. Looking forward to hear your opinions on this.
>
> Thanks,
>
> Hylke
> _______________________________________________
> aerogear-dev mailing list
> aerogear-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/aerogear-dev