Fog Documentation

[Kyle Rames]

I am interested in contributing the fog documentation. In particular, I am looking at would like to add a couple sections to the existing documentation:

* Prerequisites - Ruby versions supported and unofficially supported

* Installation - gem install via gemcutter as well as source from github

* .fog - What a .fog file, where it is located, and what it contains

* Debugging - DEBUG and EXCON_DEBUG environment variables

Does anyone have a preference where this information should be located?

I have also noticed that while fog does an excellent job of abstracting cloud concepts at a certain level there are implementation specific details. In order to better spell these out, I think we should have a page with links to implementation specific details. Similar to the approach jclouds has taken.  http://www.jclouds.org/documentation/userguide/ Thoughts?

I would also like to propose creating an example directory at root level of the fog repository.

I welcome your feedback!

Thanks!

Kyle

[geemus (Wesley Beary)]

Those sound like good things to add.

We've moved the bulk of the docs into its own repo here: https://github.com/fog/fog.github.com

So you can feel free to add extra pages/sections there and/or issues tracking missing features.

Right now most of that is pretty high level, which means that the things you are describing should fit (perhaps under 'about').

Specific implementation details are still something we've been trying to figure out. Currently we've started adding README files to specific sub directories (HP has one for instance) to go over specifics. I think this is good-enough for a start but we should probably figure out how to also organize this info on the web page.

An examples directory also could work, not sure if it should be at the root level vs in a subdirectory. For some things it makes sense to be at the root level, but I think those examples are fairly well covered in the existing web page docs for the shared/top level abstractions. That said, I'm certainly happy to discuss this further.

Thanks!
wes

[Kyle Rames]

Thanks for the feedback Wes.

I will plan on adding the Prerequisites, Installation, .fog, and debugging section to the Getting Started section and the more Rackspace specific information into a README in the appropriate location.

As far as the samples, let me come up with a few of them and maybe we will get a better feeling about where they belong.

Thanks again for the help!

Kyle

[Kyle Rames]

Now that my mind is back on documentation, I wanted to propose a (temporary) solution to this problem.

I think we should add a top level menu to fog.io called Providers. On this page we could have links to provider specific documentation and examples. In addition, I think we should incorporate #1419 into this request as well.

To optimize visibility, I think we should have a link to this page from the top level readme in the github repo.

If everyone is receptive to this I idea, I would be willing to attempt the first iteration of this page.

Kyle

[geemus (Wesley Beary)]

Sounds good to me.

--
You received this message because you are subscribed to the Google Groups "ruby-fog" group.
To unsubscribe from this group and stop receiving emails from it, send an email to ruby-fog+u...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[mb...@snap-interactive.com]

I'm happy to help, I've written a few scripts to do basic functions for AWS, and could really have used the help.    They do pretty easy things, and illustrate typical features.

Currently working on some things with VSphere, and would really like to see what other people have done.

[Kyle Rames]

Excellent! I think this information is going to be a huge boon to the fog community.

The current plan, correct me if I am wrong geemus, is to create a docs and example sub directory in each provider. Similar to what I did for Rackspace.

https://github.com/fog/fog/tree/master/lib/fog/rackspace

We are then going to add an additional page on fog.io and the github readme.md to point to this information. (You are more than welcome to get this page started if you would like.)

Kyle

[geemus (Wesley Beary)]

Sounds good to me!

[Kyle Rames]

In order to make the provider specific documentation more visible to developers, I have introduced a new top level page to fog.io in the following pull request:

https://github.com/fog/fog.github.com/pull/5

What are everyone's thoughts on this change?

Thanks!

Kyle

[Kyle Rames]

I have added a page to fog.io to make it easier to find provider specific documentation and examples. 

You can find it here => http://fog.io/about/provider_documentation.html

It contains all of the information I could find in the fog rep. If you could add any missing resources that would be great. 

The page source is here => https://github.com/fog/fog.github.com/blob/master/about/provider_documentation.markdown

Thanks!

Kyle