Fwd: Re: Implementation Guide

[Ron Wheeler]

Just to show that we are not the only Apache project trying to make
sense of documentation.

Ron


-------- Original Message from Shindig project--------

Hi all,

the question is how we should balance the material between Apache CMS and
Confluence.  I think that all technical guides and resources should go into
Confluence - making it the official documentation space, rather than just a
wiki - and all the high-level reference / 'marketing' / news material into
the web site.

I'm having a look at different Bootstrap themes in order to select a few,
submit the initial list and let the people involved decide.  As I've
already said, I think we should use a vibrant theme that shouts "Hey, have
a look inside. It's good stuff!" therefore my attention is grabbed by
'landing page' / 'agency' parallax type themes.

One thing that is missing though, is a kick-ass Shindig logo.  Is someone
willing to create one?  Raj, if you could suggest a Bootstrap theme that
would be great.

In the following days, I'll post a selection of themes as a reference and
we can vote.  Also, I'll try and write down a suggested link structure for
the new site and also a scaffolding for the technical docs in Confluence.

Let me know what you think.

Cheers,
Chris

On Wed, Oct 8, 2014 at 2:27 AM, Ryan Baxter <[hidden email]> wrote:

> OK well for reference check out the website docs [1].  Let me know if
> you have any problems.
>
> [1] http://shindig.apache.org/documentation_website.html
>
> On Tue, Oct 7, 2014 at 7:24 PM, Raj Janorkar <[hidden email]>
> wrote:
> > Hi Ryan,
> >
> > In my work place i am using Confluence. so i don't think there will be
> > problem to me.
> >
> > Regards,
> > Raj
> >
> > On Tue, Oct 7, 2014 at 7:17 AM, Ryan Baxter <[hidden email]> wrote:
> >>
> >> Chris and Raj, appreciate you both stepping up!  Are you familiar with
> >> how to use Apache CMS to edit the Shindig site?
> >>
> >> On Thu, Oct 2, 2014 at 7:09 AM, Raj Janorkar <[hidden email]>
> >> wrote:
> >> > I am also in.
> >> > though i am new here but ready to help wherever i can.
> >> >
> >> > Thank you for this great step.
> >> >
> >> > On Thu, Oct 2, 2014 at 7:14 PM, Chris Spiliotopoulos <
> >> > [hidden email]> wrote:
> >> >
> >> >> Hi all,
> >> >>
> >> >> I am willing to take the first step forward on this but I expect all
> >> >> the
> >> >> people in this group to contribute / suggest / vote on important
> things
> >> >> that will make the Shindig project come back to life and start
> >> >> receiving
> >> >> attention.  Based on the steps that Ryan suggested:
> >> >>
> >> >>
> >> >> > *1.  We use the Shindig site as the place to keep the
> documentation.
> >> >> > It
> >> >> is
> >> >> > CMS based [1] so no need to know how to write HTML.*
> >> >>
> >> >>
> >> >> First we need to decide on an awesome & clean theme for the website
> >> >> that
> >> >> will be responsive and attractive.  As Bootstrap is already being
> used
> >> >> that
> >> >> should be no prob, but we need to use a theme that will rock.  Please
> >> >> suggest themes from other sites that you find attractive and user
> >> >> friendly.  For instance, I find the SailsJS <http://sailsjs.org/>
> theme
> >> >> very clear for reading.  Also, if someone could deal with the art
> work
> >> >> that
> >> >> would be very useful.
> >> >>
> >> >>
> >> >>
> >> >> >
> >> >> > *2.  We create a getting started guide, containing the minimal set
> >> >> > of steps to get someone up and running.*
> >> >>
> >> >>
> >> >> >
> >> >> > *3.  We create a detailed implementation guide that addresses how
> >> >> > someone
> >> >> > would extend Shindig to build their own implementation.*
> >> >>
> >> >>
> >> >> Next, we need to make a map of the current structure of the web site
> >> >> and
> >> >> then suggest alternatives on how the new site should be structured.
> >> >> The
> >> >> key here is that it should be self explanatory and guide you
> >> >> step-by-step
> >> >> on how to do from the simplest to the most advanced task.  Newcomers
> >> >> should
> >> >> feel comfortable with it so that they start with an appetite to learn
> >> >> more
> >> >> about this project.
> >> >>
> >> >> This part requires an initial gathering of all existing resources and
> >> >> cleansing.  Everything should be relevant to the latest version
> >> >>  of the framework.  A few months ago I had created a GitHub project
> >> >> <https://github.com/theChefArchitect/os-examples-container-embedded>
> >> >> with
> >> >> a
> >> >> sample embedded container in a Spring web app written for this
> purpose.
> >> >> I've also noticed that the maintenance of the PHP version has
> stopped.
> >> >> All
> >> >> these cluttered resources should be gathered in one place initially
> and
> >> >> then decide which of them should be used as a reference for the new
> >> >> documentation.
> >> >>
> >> >>
> >> >> > *4.  In the process of doing this we cleanup/consolidate the
> Shindig
> >> >> > site
> >> >> > and the wiki.*
> >> >>
> >> >>
> >> >> One important thing that should be decided is where the
> documentation /
> >> >> tutorials should be hosted.  At the moment the web site acts as a
> proxy
> >> >> for
> >> >> different documentation locations around the web and some hard-core
> >> >> tech
> >> >> docs live under Atlassian's Confulence site
> >> >> <https://opensocial.atlassian.net/wiki/display/OSREF>. What's the
> story
> >> >> with that?  Will the documentation be hosted under Confluence or
> under
> >> >> the
> >> >> web site?
> >> >>
> >> >> Overall, this task requires collaborative effort and should be done
> in
> >> >> baby
> >> >> steps.  Documentation / guides are important but then there are
> plenty
> >> >> of
> >> >> other stuff needed to make this project gain a vibrant community -
> e.g.
> >> >> gadgets hosted on the site for tutorials and show cases, API
> >> >> documentation
> >> >> / integration, social media presence, etc.
> >> >>
> >> >> Looking forward to your responses.
> >> >>
> >> >> Cheers,
> >> >> Chris
> >> >>
> >> >>
> >> >> On Thu, Oct 2, 2014 at 12:12 AM, Ryan Baxter <[hidden email]>
> >> >> wrote:
> >> >>
> >> >> > Does anyone feel especially passionate about this topic and want to
> >> >> > step up and take the lead on this?
> >> >> >
> >> >> > On Wed, Sep 17, 2014 at 4:26 AM, Darren Bond <[hidden email]>
> >> >> wrote:
> >> >> > > Hi Ryan,
> >> >> > >
> >> >> > > This sounds like a really great start. I'm sure a clean and clear
> >> >> > getting started guide + detailed implementation guide that can be
> >> >> > easily
> >> >> > located on the Shindig site will make a huge difference on the
> >> >> > take-up of
> >> >> > this impressive framework.
> >> >> > >
> >> >> > > Kind regards,
> >> >> > >
> >> >> > > Darren
> >> >> > >
> >> >> > >
> >> >> >
> >> >>
> >> >>
> >> >>
> >> >> --
> >> >> Chris Spiliotopoulos
> >> >>
> >> >> Solutions Architect
> >> >>
> >
> >
>

--
Chris Spiliotopoulos

Solutions Architect