You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@deltacloud.apache.org by Dagmar Husarova <dh...@redhat.com> on 2012/02/24 17:18:48 UTC
sitemap - basic structure
Hi!
So, I've tried to review the basic structure of deltacloud.apache.org.
There is a current state described in the attachment and then a revised
version according to my idea. I've added some comments. It's just a
basic structure of a web, but I think it's good to give you an
impression of what I'm thinking about. I'm still working on the
Developers section - there is a huge amount of information, which needs
to be dived into a smaller parts and to be connected in easily
accessible way.
Please, feel free to let me know your opinion.
--
Dagmar Husarova
Intern | Red Hat. Inc.
Re: sitemap - basic structure
Posted by Dagmar Husarova <dh...@redhat.com>.
Hi!
Thank you for your comments, I've tried to review the structure
according to them.
> Use the API
> How to use API, install instructions for clients
>
> - I would love to see there also some use-cases (like launching an instance, etc.)
> - I would recommend to have single page for every client (not just list them). Each page should include link to sources and install instructions (+ contact to author)
There could be a list of links or a box with links divided into two
sections:
How to use API
Launching an instance
Other use-cases (Right now I'm not able to say, what else
should it be. Could you, please, give me a clue?)
Libdeltacloud
Clients - link to sources and install instructions of a specific client
Deltacloud Ruby Client
Other clients (single page for every client)
> Contribute
> - I'm not sure if 'this section is the right place for 'write and run a test'. Tests should be part of every patch/driver :-)
In that case I would add a link to the page 'write and run a test' at
the end of the patch and driver section, if that sounds better.
> - I miss something like 'Propose an idea'.
> - Writing documentation is another great way how to contribute :-)
> - In "report bug' it will be important to tell people why we have Bugzilla and JIRA and Teambox and also why we're using all three :)
Revised version of 'Contribute' page:
1) short text about using the Deltacloud github mirror and a license
agreement + link to the 'Getting the sources' page (contains where and
how to get sources, development dependencies, how to build from source
and install the Deltacloud gem + link to a list of paths to most
important files and directories in the Deltacloud directory structure)
2) a box titled How can I contribute? with links:
'Send a patch'
'Write a provider driver'
'Report bug' - instructions how to report a bug and why we have
Bugzilla and JIRA and Teambox and also why we're using all three
'Propose an idea' - instructions how to propose any other ideas (to
improve Deltacloud, the website etc) + a contact
'Writing documentation' - instructions how to write documentation,
where to send, eventually some tips what documentation we need
at the moment
> - I would love to have 'libdeltacloud' documentation in 'Use the API' section
> - Drivers should rename to 'Drivers API'
> - Clients should point to 'Use the API' client section.
> - Deltacloud Ruby client is one of the 'clients' we have. It is a separate library/gem.
> - We (/me) need to work on proper rdoc/yard docs for client.
I've also tried to go through API Documentation and make some notes:
'API Documentation'
*I still don't know if it is necessary to have the banner with links to
main chapters of documentation under the top-level links. However, it
seems to me that it's good to outline a structure of the documentation
on the first page (the main chapters of REST API, what you can find in
'Drivers' section, etc.) with links to relevant sub-pages.*
'REST API'
'Drivers API' - I would start the page with general information
about drivers and a list of currently supported drivers and
than add a link to a next page 'notes on specific drivers.
'Clients' - link to 'Use the API' client section
'REST API'
I think that instead of writing headers this way: "GET /api/firewalls"
it's better to use something like that: "Get a list of all firewalls".
It gives you a better impression of what's going on here. And it'll be
much easier to use a header as a link. We may need to divide some
chapters because of their length and than it will be useful.
For example chapter 3.7:
3.7 Firewalls
Get a list of all firewalls
Get details of a specified firewall
Create a new firewall
Delete a firewall
Create a firewall rule
Delete a firewall rule
As concerns the REST API itself, I am considering this possibility:
First thing you should see is the content of the documentation (just the
numbered chapters). Content should somehow stay on the page you are
viewing (could be a box on the top of the page on the left or right
side) and only the text of the page is changing -> after you open 'REST
API' page, you'll see a text of chapters "1. Introduction" and "1.1
Collections" and also a box with content. There'll be always link to a
next chapter on the end of the page (while the content is still there to
jump further or back in the documentation according to needs of a user).
However, Instances, Firewalls or Blob Storage still remain too long and
you must scroll down a lot, so maybe it would be good to divide them
into smaller parts, too, and connect them with links (in similar way
like chapters). On the other hand we have really short chapters (1.2 -
1.7) which can create just one single page.
Please, let me know, what you think!
--
Dagmar Husarova
Intern | Red Hat. Inc.
Re: sitemap - basic structure
Posted by Michal Fojtik <mf...@redhat.com>.
Hi Dagmar,
First, it's great to see this progress here. I think it's really useful to see our site structure
in this form. My few comments to proposed site structure:
Use the API
How to use API, install instructions for clients
- I would love to see there also some use-cases (like launching an instance, etc.)
- I would recommend to have single page for every client (not just list them). Each page should
include link to sources and install instructions (+ contact to author)
Contribute
there could be a box titled 'How can I contribute?' with links:
'Send a patch'
'Write a provider driver'
'Write and run a test'
'Report bug'
- I'm not sure if 'this section is the right place for 'write and run a test'. Tests should be
part of every patch/driver :-)
- I miss something like 'Propose an idea'.
- Writing documentation is another great way how to contribute :-)
- In "report bug' it will be important to tell people why we have Bugzilla and JIRA and Teambox
and also why we're using all three :)
'API Documentation' (As I see it, this is a source of complex information about API interesting and relevant mainly for developers. I think it should stay separated from 'Contribute' page and 'Use the API' page. It seems to me easier this way. If someone needs to see the documentation, it's right there on the top of the page as well as the link to 'Contribute' page. It would be much harder to find what you are looking for if these two were hidden in another link.)
'REST API'
'Drivers'
'Clients'
'The Deltacloud Ruby Client'
'Other HTTP Clients'
'libdeltacloud'
- I would love to have 'libdeltacloud' documentation in 'Use the API' section
- Drivers should rename to 'Drivers API'
- Clients should point to 'Use the API' client section.
- Deltacloud Ruby client is one of the 'clients' we have. It is a separate library/gem.
- We (/me) need to work on proper rdoc/yard docs for client.
just my .20 cents ;-)
-- michal
Michal Fojtik
http://deltacloud.org
mfojtik@redhat.com
On Feb 29, 2012, at 10:05 AM, Dagmar Husarova wrote:
>
> Hi!
>
> Thanks for your ideas, David. I found them very useful. So I've made a new version of a site map basic structure. Please, see the attachment and let me know what you think.
> --
> Dagmar Husarova
> Intern | Red Hat. Inc.
> <sitemap2.txt>
Re: sitemap - basic structure
Posted by Dagmar Husarova <dh...@redhat.com>.
Hi!
Thanks for your ideas, David. I found them very useful. So I've made a
new version of a site map basic structure. Please, see the attachment
and let me know what you think.
--
Dagmar Husarova
Intern | Red Hat. Inc.
Re: sitemap - basic structure
Posted by Justin Clift <jc...@redhat.com>.
On 28/02/2012, at 8:15 AM, Justin Clift wrote:
> On 25/02/2012, at 12:26 PM, David Lutterkort wrote:
> <snip>
>> 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/
>
> Converting to nanoc probably won't be *too* difficult. I've done this
> for the Aeolus site, and the hardest part was getting nanoc to match
> the webby output directory structure.
>
> Since the Deltacloud site is being redone, matching the webby output
> structure probably doesn't matter. :)
>
> If someone needs basic "get it running" type of assistance, I can
> probably help.
This *might* be helpful:
https://github.com/justinclift/deltacloud-website
It's a copy of the Deltacloud svn website as it stands, with
an initial conversion to nanoc.
Not being a Ruby programmer though, I don't really get how the
"render" thing works. So I've commented those out, and moved
the "_foo.haml" partial files to a new dir called "no_idea".
Won't be spending any more time on it myself, but hoping it's
useful for Dagmar.
:)
Regards and best wishes,
Justin Clift
> Regards and best wishes,
>
> Justin Clift
>
> --
> Aeolus Community Manager
> http://www.aeolusproject.org
>
--
Aeolus Community Manager
http://www.aeolusproject.org
Re: sitemap - basic structure
Posted by Justin Clift <jc...@redhat.com>.
On 25/02/2012, at 12:26 PM, David Lutterkort wrote:
<snip>
> 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/
Converting to nanoc probably won't be *too* difficult. I've done this
for the Aeolus site, and the hardest part was getting nanoc to match
the webby output directory structure.
Since the Deltacloud site is being redone, matching the webby output
structure probably doesn't matter. :)
If someone needs basic "get it running" type of assistance, I can
probably help.
Regards and best wishes,
Justin Clift
--
Aeolus Community Manager
http://www.aeolusproject.org
Re: sitemap - basic structure
Posted by David Lutterkort <lu...@redhat.com>.
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
>