Re: sitemap - basic structure

[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

[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.