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 >
