jclouds-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Everett Toews <everett.to...@RACKSPACE.COM>
Subject Re: Documentation, let's discuss
Date Wed, 29 May 2013 02:39:59 GMT
On May 28, 2013, at 9:12 PM, Becca Wood wrote:

Hi everyone,

There are currently several conversations going on about docs,

The only conversation that I think is *currently* on-going is "Where we host non-wiki documentation".
Personally, I think it's going well and has been constructive.

and the statements from some folks are blindsiding me as I read from thread to thread.

I'm not going to speculate as to what you mean here. There has been a lot of doc discussion
in the past few weeks but it's been mostly resolved apart from the discussion above.

It would be great to have a discussion around what everyone does not like about the current
docs process and why and how it should be changed.

I think this is moving forward in the discussion "Where we host non-wiki documentation" but
I may have missed something.

It would also be good to address the aesthetic and navigability of the website.

I suspect this has to do with my comment about the L&F of jclouds.org<http://jclouds.org>.
My apologies, I should have started that as an entirely separate thread rather than mixing
it into "Where we host non-wiki documentation". Lesson learned.

I should have been more specific. Here are some of my thoughts in no particular order.

1. jclouds.org<http://jclouds.org> is very static. We have a very vibrant community
w.r.t. releases, issues, blog posts, mailing lists, Twitter, and GitHub. This could be reflected
in jclouds.apache.org<http://jclouds.apache.org> with Javascript. All of it may or may
not be appropriate but let's show the world that we're constantly improving jclouds and it's
a thriving project.

2. Tiny grey text on grey background is difficult to read. I avoid showing it during presentations
because of this.

3. http://www.jclouds.org/news/ is broken.

4. I confess to an element of Bootstrap is the new hotness but when you stack jclouds.org<http://jclouds.org>
side-by-side with http://shiro.apache.org/ or even http://lucene.apache.org/ we are less engaging.

5. http://www.jclouds.org/documentation/community/ is links only, no text at all.

I am not laying this at the feet of anyone. All of us are responsible for the state of jclouds
documentation. It isn't going to be an overnight fix.

Since I am responsible for a good deal of the current docs process on GitHub and the way the
current website looks, it would be great to get some feedback on the strengths and weaknesses
of both.

The aim of this discussion is to help us collect our thoughts in one place and create a more
solid and contributor friendly process moving forward.

I don't want to be a hinderance or the single point of failure in our docs process, so if
anyone is confused or has concerns about the current process, please let me know.

I appreciate this. You're not a hinderance or a SPOF. In Apache every single one of us are
as responsible for doc as you are. It's certainly your area of expertise but all of the other
committers share equally in the responsibility to make jclouds doc great.

Everett

Mime
View raw message