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.
