4:37 a.m.
Hi,
What I get from this thread is that we like the colour section idea, but we don’t want to
re structure the entire site. So what we need to discuss is how are we going to use these
sections if we don’t restructure. What I like about them is that it emphasises that our
API’s are similar for all platforms and that we only have one document explaining for
instance what pipes are. But the menu, doesn’t fit into this new colour scheme, so we need
some decisions about how we are going to move forward.
Based on the work Corinne did with the introduction of sass I’ve had a go at implementing
a bit what Hylke proposed, have a look at my sass branch
https://github.com/edewit/aerogear.org/tree/saas and the page I’ve updated
http://localhost:4000/docs/guides/aerogear-android/AerogearAndroidPipes101/ to be in
section layout. Don’t look at the header and footer as I haven’t changed those.
There are a couple of things that I don’t like about the current implementation, to enable
the code blocks I’ve added some html into the asciidoc and some jquery magic in the
layout. Maybe we could make this better by chaining the rendering/backend or by
introducing some sort of plugin into asciidoc? Other then that, I’m sure Hylke sees a lot
of things that are still off, but it’s a start.
What do you think?
Cheers,
Erik Jan
p.s
example picture https://www.dropbox.com/s/qtc4g0xwnyi0p41/Example.tiff
4:53 a.m.
New subject: Fwd: Website restructure
On Mon, Jan 20, 2014 at 11:37 AM, Erik Jan de Wit <edewit(a)redhat.com> wrote:
that example screenshot looks very nice
--
Matthias Wessendorf
blog: http://matthiaswessendorf.wordpress.com/
sessions: http://www.slideshare.net/mwessendorf
twitter: http://twitter.com/mwessendorf
5:35 a.m.
Looks good!
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.
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.
Karel
On Mon, 20 Jan 2014 11:37:28 +0100
Erik Jan de Wit <edewit(a)redhat.com> wrote:
5:44 a.m.
New subject: Fwd: Website restructure
On Mon, Jan 20, 2014 at 12:35 PM, Karel Piwko <kpiwko(a)redhat.com> wrote:
Looks good!
+1 I like the dracula theme !
+1 , that would be really cool. I came accross such a layout on
https://www.paymill.com/fr-fr/documentation/reference/api-reference/#docu...
,
check on the right, you have a tab where you can switch between different
languages, the snippet is updated.
There are also some online apps that does the job for you like apiary.ioand
https://www.mashape.com
11:31 a.m.
New subject: Website restructure
Hello All
I think the original idea was to have a common text. I think we could have common part for
exemple:
http://aerogear.org/docs/guides/aerogear-android/AerogearAndroidPipes101/
http://aerogear.org/docs/guides/iOSCookbook/ (section on pipe)
http://aerogear.org/docs/guides/GetStartedAeroGearJS.html (section Pipeline & Pipes)
all defined Pipe and pipeline, they could have a common part but of course this will
involve some serious documentation refactoring.
=> first task make common smaller pages
However, we still need platform specific text. In all the previous exemple we give code
snippet + code explantion. We could extend the tab to include text + sample.
What will be nice to have as a POC is also:
- the main documentation page with the 3 features section: Core/Push/Security
- when we pick core, the display of the list of features: Pipe, Store etc…. which is
actually missing from Hylke draft.
- where do we put documentation like:
http://aerogear.org/docs/guides/GetStartedAndroid/
which is not features oriented but goes into the category setup
I’ll fork your branch and try to see how we can refactor documentation and give you more
concrete feedbacks shortly.
For the menu color I guess the best person to help is Hylke.
++
Corinne
On 20 Jan 2014, at 12:44, Sebastien Blanc <scm.blanc(a)gmail.com> wrote:
12:36 p.m.
New subject: Website restructure
Yeah, that was my take on it as well, and because we explain how to use these things in
only one document with some platform specific parts it will also be a place to verify that
our api’s are close to one another.
+1 if there is a need for that that is very do-able
What will be nice to have as a POC is also:
- the main documentation page with the 3 features section: Core/Push/Security
Okay that is one thing I wasn’t certain on, that will mean restructure of the site to
create these sections based on ‘functionality’ instead of platform. Does that mean you
want to move away from the per platform split, or does it mean that you want to keep
both?
K, have a closer look and I’ll wait in the mean time Hylke do you have some ideas for
keeping the menu or maybe integrating it differently?
6:39 a.m.
New subject: Website restructure
On 20/01/2014 18:36, Erik Jan de Wit wrote:
Hey Erik,
This is great work! :)
It would be nice if the body text is as generic as possible so that it
always works with the code in every language, but there may be some
situations where this isn't possible. So yes, your suggestion of a small
comment section in the code snippet would be a good solution for that.
This is probably the biggest change and the main point of the
restructure to keep everything understandable and easy to navigate. I'd
say yes, but am not sure if everybody agrees with me (but I hope to
convince them :).
We may not need the menu anymore. What we do need is some kind of side
bar in the documentation to quickly jump between the submodules
(Core/Sync/Push/etc.). I'll have a look at that and post some mockups here.
Anyway, it's great to see progress in this area. Good job and I will
have a look at the branch. :)
Hylke
7 a.m.
New subject: Website restructure
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
On 22 Jan 2014, at 13:03, Karel Piwko <kpiwko(a)redhat.com> wrote:
8:58 a.m.
New subject: Website restructure
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(a)redhat.com> wrote:
12:08 p.m.
New subject: Website restructure
Hey,
On 24/01/2014 14:58, Corinne Krych wrote:
The [2] link is on localhost. :)
How about we try it out for Pipes and see how it goes? Yes, we probably
would need to move some stuff out to other sections, but that's ok.
We'll have a better ideas what to do with the "excess" docs once we try
any simplify the multiple documents into one.
Here's the idea for the scopes I had:
- Examples => High level overview of AeroGear concepts and code snippets
about how they're used. Not neccesarily big programmes.
- Documentation
- Getting started => Download and setup
- API Browser => just a link to the full API overview
- Guides: We can go more all out here. Tutorials, example projects, more
complex configurations, etc. Basically everything else that doesn't fall
into the above categories. :)
I know it's a lot of work... I do think it's the best way to go. I'd be
happy to help out on this too, though I've absolutely no clue on the
topic, but that may actually be a good thing for explaining stuff to
people new to the concepts. :)
Yes, I'll
send you those. Don't worry about the theming too much, as we
haven't really discussed that yet. The "Dracula" theme was more of an
example of how we can use colours to mark different sections of the
project/site. So if you'd like to see things different, let me know! :)
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
I've actually added it back in the mockup
(see the other email on the
thread). It was more of a time thing that I hadn't added it yet. It's
back now.
Hylke
6:25 a.m.
New subject: Website restructure
On Fri, 24 Jan 2014 15:58:27 +0100
Corinne Krych <corinnekrych(a)gmail.com> wrote:
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
11:14 a.m.
New subject: Website restructure
Hi Corinne,
I've updated the mockup with a sidebar to show the structure a bit
better:
https://raw2.github.com/hbons/aerogear-design/master/website-restructure/...
I think this is mostly like what you've described.
Other changes are a simple menubar and the platform icons on the main
page that we decided we wanted back.
"where do we put documentation like:
http://aerogear.org/docs/guides/GetStartedAndroid/ which is not features
oriented but goes into the category setup "
This should actually go right below the download options (see the second
page in the mockup). There will also a link to it in the Docs sidebar.
It's a bit hard to explain in an email, I think the mockup explains it
better. :)
Hylke
On 20/01/2014 17:31, Corinne Krych wrote:
2:49 a.m.
New subject: Website restructure
Hello Hylke,
Somehow I can’t make AG core work in the proposed page2 and page 3 as per your screen
shot, I rather have page3 in your page3 and then page 3 will be a detailled example with
download link to cookbook.
In the page2 we could have download button at the top and documentation with code snippet
at he bottom.
General setup documentation should amybe fit into dowlad section. Note that not all
category nee setup. for AG Core there isn’t any complicated set up. It’s just a lib.
wdyt?
Corinne
On 24 Jan 2014, at 18:14, Hylke Bons <hbons(a)redhat.com> wrote:
8:22 a.m.
New subject: Website restructure
ok true it’s confusing, let’s name the,:
page 1 - Home page
page 2- get it
page 3- examples
Trying to refactor page-3 in code snippets is feasable but you loose lot’s of usefull
documentation which is speciific to the platform.
Page-3 is some shallow exemple. in ag.org we’ve got lots of detailled docuemntation i
don’t want to throw again so my suggestion was:
- either aff page-4 level with detailled doc
- or remove/change page-2(level-2) to be the shallow example anf page-3(level-3) become
detailled ex
Does it make more sense? can you see my pb on this refactoring documentation exercice?
++
Corinne
On 03 Feb 2014, at 15:16, Hylke Bons <hbons(a)redhat.com> wrote:
4077
days inactive
4091
days old
18 comments
6 participants
participants (6)
-
Corinne Krych -
Erik Jan de Wit -
Hylke Bons -
Karel Piwko -
Matthias Wessendorf -
Sebastien Blanc