deltacloud-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Lutterkort <lut...@redhat.com>
Subject Re: sitemap - basic structure
Date Sat, 25 Feb 2012 01:26:45 GMT
Hi Dagmar,

On Fri, 2012-02-24 at 17:18 +0100, Dagmar Husarova wrote:
> So, I've tried to review the basic structure of deltacloud.apache.org.

Thanks for doing this; besides content changes, there's also a dire
technical need for the site: it's still generated with webby[1], even
though that's not being developed any more[2], and should really be
ported to nanoc[3]

Comments on your proposal below,
David

[1] http://webby.rubyforge.org/
[2] http://groups.google.com/group/webby-forum/browse_thread/thread/41362c82c63f5276
[3] http://nanoc.stoneship.org/

> Home
>         Deltacloud gives you
>         News
> 
> Download
>         Get Deltacloud
>                 Getting the sources
>         The Deltacloud Ruby Client
>         libdeltacloud
>         Your name here
> 
> *Get Deltacloud should probably be a single page. The description how
> to download and install Deltacloud is now split into two parts in
> Download and in Documentation/Installation.

There's two different audiences that we need to serve:
     1. users (might be developers, but they couldn't care less what the
        server looks like) They want to get the bits as quickly as
        possible, meaning they want to get a server running somewhere,
        and possibly a client installed and working with their code.
        They need to know how to install the pertinent
        RPMS/gems/tarballs and start the server
     2. developers, i.e., people who want to modify the server or client
        code; those are the ones who need to know about git checkouts,
        library prerequisites etc.

The site should make it easy for both types of people to find what they
need. I would actually replace the three entries 'Download',
'Developers' and 'Documentation' with 'Running the API', 'Using the
API', and 'Contribute' and shuffle content around accordingly; content
in these sections should be

      * 'Running the API': (1) how to install a server from released
        bits (yum/gem) (2) links and directions for using the public DC
        instances
      * 'Using the API': (1) install instructions for clients (2) API
        documentation (though I am not sure if we shouldn't leave that
        at the top-level as 'API Docs')

>  So it would be better to move Documentation/Installation to Get
> Deltacloud. I would also change the order of Installation page a
> little bit: 1. Installation dependencies 2. Installation of Deltacloud
> itself 3. quick-start guide.

As a user, you shouldn't have to worry about installation dependencies -
we should recommend yum and gem installs, which will take care of
dependencies.

>  Getting the sources is already a part of Developers section. The
> Deltacloud Ruby Client and Other HTTP clients should by moved to a new
> page Clients (located in Developers section>Documentation).

Yes, I think that would be the right place for libdeltacloud, too.

>  The same with libdeltacloud. Your name here makes no sense to me at
> this page, I think it's better to write something like that to the
> homepage and also to developers page.*

Agreed; I think we should add a box titled 'Next Steps' underneath
'Deltacloud gives you' across the whole page with a few bullets:
      * How do I run the Deltacloud server (link to server install
        instructions)
      * How do I use Deltacloud (link to client docs)
      * How do I contribute to Deltacloud (link)

> Documentation *As the whole section is the matter of interest mainly
> for developers, it should be included in the Developers section -
> apart from installation. Installation together with Get Deltacloud
> creates a single page.*

As I said above, there are different audiences, and we should structure
the docs accordingly; OTOH, I do like a big honking 'Documentation' link
when I try to get to know a new project. I agree with combining
'Installation' with 'Get Deltacloud'

The other sections under 'Documentation' are:
      * REST API: interesting to app developers, either those using the
        API directly, or through a client
      * Drivers: interesting to devs who want to modify the server code
      * Ruby client: interesting for app developers who use the Ruby
        client
      * libdeltacloud: interesting for app developers working in C (very
        few, I'd assume)

Let me know what you think of the above. Besides improving the site,
there's also a huge need to document the CIMI work we've been doing. At
a minimum, we'd need to document how to run the CIMI frontend, and how
to deploy the CIMI client app.

David
> 


Mime
View raw message