You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@jclouds.apache.org by Becca Wood <si...@apache.org> on 2013/05/29 03:12:57 UTC
Documentation, let's discuss
Hi everyone,
There are currently several conversations going on about docs, and the
statements from some folks are blindsiding me as I read from thread to
thread.
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. It
would also be good to address the aesthetic and navigability of the
website. 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.
Thanks,
Becca
Re: Documentation, let's discuss
Posted by Everett Toews <ev...@RACKSPACE.COM>.
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
Re: Documentation, let's discuss
Posted by Everett Toews <ev...@RACKSPACE.COM>.
On May 29, 2013, at 2:51 PM, Matt Stephenson wrote:
> We lack docs and references on how jclouds is used by other projects.
> We're a nexus for multiple different projects (jenkins to openstack,
> maginatics to s3, etc). We should highlight this more in the website so
> that it compels projects to integrate with various iaas's through jclouds
> so they gain portability. At this point the main website is too technical
> for most audiences, and doesn't paint a compelling story to pull others in.
Agreed. I like this a lot.
> Otherwise, I think the layout is pretty good, it's better than most
> opensource projects with the same number of active contributors. I believe
> as we grow and recruit more talent into our community, we can find ways to
> improve it.
Agreed.
Everett
Re: Documentation, let's discuss
Posted by Everett Toews <ev...@RACKSPACE.COM>.
On May 29, 2013, at 2:51 PM, Matt Stephenson wrote:
> We lack docs and references on how jclouds is used by other projects.
> We're a nexus for multiple different projects (jenkins to openstack,
> maginatics to s3, etc). We should highlight this more in the website so
> that it compels projects to integrate with various iaas's through jclouds
> so they gain portability. At this point the main website is too technical
> for most audiences, and doesn't paint a compelling story to pull others in.
Agreed. I like this a lot.
> Otherwise, I think the layout is pretty good, it's better than most
> opensource projects with the same number of active contributors. I believe
> as we grow and recruit more talent into our community, we can find ways to
> improve it.
Agreed.
Everett
Re: Documentation, let's discuss
Posted by Matt Stephenson <ma...@apache.org>.
We lack docs and references on how jclouds is used by other projects.
We're a nexus for multiple different projects (jenkins to openstack,
maginatics to s3, etc). We should highlight this more in the website so
that it compels projects to integrate with various iaas's through jclouds
so they gain portability. At this point the main website is too technical
for most audiences, and doesn't paint a compelling story to pull others in.
Otherwise, I think the layout is pretty good, it's better than most
opensource projects with the same number of active contributors. I believe
as we grow and recruit more talent into our community, we can find ways to
improve it.
On Tue, May 28, 2013 at 6:12 PM, Becca Wood <si...@apache.org> wrote:
> Hi everyone,
>
> There are currently several conversations going on about docs, and the
> statements from some folks are blindsiding me as I read from thread to
> thread.
>
> 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. It
> would also be good to address the aesthetic and navigability of the
> website. 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.
>
> Thanks,
>
> Becca
>
Re: Documentation, let's discuss
Posted by Andrew Bayer <an...@gmail.com>.
I have absolutely no sense of aesthetics, so I'm not the right person to
ask in re: navigability and aesthetics in general, but I do have two
requests:
- Increase the font size of the text on pages - it's just too small to read
on a big monitor without blowing up the page considerably.
- There should really be an easy link to find that'll get you to the
javadocs for a given release. That's way too important to be hard to find
or not there at all.
A.
On Tue, May 28, 2013 at 6:12 PM, Becca Wood <si...@apache.org> wrote:
> Hi everyone,
>
> There are currently several conversations going on about docs, and the
> statements from some folks are blindsiding me as I read from thread to
> thread.
>
> 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. It
> would also be good to address the aesthetic and navigability of the
> website. 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.
>
> Thanks,
>
> Becca
>
Re: Documentation, let's discuss
Posted by Matt Stephenson <ma...@apache.org>.
We lack docs and references on how jclouds is used by other projects.
We're a nexus for multiple different projects (jenkins to openstack,
maginatics to s3, etc). We should highlight this more in the website so
that it compels projects to integrate with various iaas's through jclouds
so they gain portability. At this point the main website is too technical
for most audiences, and doesn't paint a compelling story to pull others in.
Otherwise, I think the layout is pretty good, it's better than most
opensource projects with the same number of active contributors. I believe
as we grow and recruit more talent into our community, we can find ways to
improve it.
On Tue, May 28, 2013 at 6:12 PM, Becca Wood <si...@apache.org> wrote:
> Hi everyone,
>
> There are currently several conversations going on about docs, and the
> statements from some folks are blindsiding me as I read from thread to
> thread.
>
> 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. It
> would also be good to address the aesthetic and navigability of the
> website. 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.
>
> Thanks,
>
> Becca
>
Re: Documentation, let's discuss
Posted by Everett Toews <ev...@RACKSPACE.COM>.
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
Re: Documentation, let's discuss
Posted by Andrew Bayer <an...@gmail.com>.
I have absolutely no sense of aesthetics, so I'm not the right person to
ask in re: navigability and aesthetics in general, but I do have two
requests:
- Increase the font size of the text on pages - it's just too small to read
on a big monitor without blowing up the page considerably.
- There should really be an easy link to find that'll get you to the
javadocs for a given release. That's way too important to be hard to find
or not there at all.
A.
On Tue, May 28, 2013 at 6:12 PM, Becca Wood <si...@apache.org> wrote:
> Hi everyone,
>
> There are currently several conversations going on about docs, and the
> statements from some folks are blindsiding me as I read from thread to
> thread.
>
> 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. It
> would also be good to address the aesthetic and navigability of the
> website. 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.
>
> Thanks,
>
> Becca
>