Re: Doc Updates
Fred, The updated doc I saw was this one: http://cloudstack.apache.org/docs/en-US/Apache_CloudStack/4.2.0/html/Installation_Guide/index.html If you look at this section: http://cloudstack.apache.org/docs/en-US/Apache_CloudStack/4.2.0/html/Installation_Guide/management-server-install-flow.html#prepare-system-vm-template You will see the updated templates. Not sure what else changed. On Wed, Oct 16, 2013 at 4:16 AM, Fred Messinger fredmessin...@gmail.comwrote: David, Would you mind posting the url for the update you reference? I'm looking at the 4.2 view on buildacloud.com and the last update there was a month ago. So I assume I'm looking in the wrong place. Thanks, Fred On Mon, Oct 14, 2013 at 2:07 PM, David Nalley da...@gnsa.us wrote: And just as a heads up, thanks for help from Prasanna and Travis, I've published an updated version of the IG for 4.2, hopefully that at least gets us 'installable'. --David On Thu, Oct 10, 2013 at 2:10 PM, David Nalley da...@gnsa.us wrote: On Thu, Oct 10, 2013 at 1:53 PM, Travis Graham tgra...@tgraham.us wrote: What's an acceptable/expected timeframe for rolling out the published fixes once a patch has made it's way in? Is that something that can be automated after a successful Jenkins run? Travis It depends on the scope of changes. For a document like the release notes, assuming someone already has an updated SVN tree, it shouldn't take more than 30 minutes to update, and it could happen pretty regularly. If it's every document in a single release, that's historically taken the better part of a day. I don't think we'll get away with getting it to happen in an automated fashion, simply because it requires commit access to SVN, which is tied to an individual, which means someone would need to expose their creds, which would be a bad thing. --David
Re: Doc Updates
It would be nice, if there is an update on the Release Note section, for upgrading procedure - since system VMs does not start after upgrade from 4.x to 4.2... I know there is bug documented, and should be fixed with 4.2.1.. ? Best On 16 October 2013 03:08, Carlos Reategui car...@reategui.com wrote: Thanks for updating it. Without knowing what to look for in the prepare system vm template section I would not have known that it was updated. Would it make sense to have a date in the header or footer with the last content update date for a page? Also do you know if the upgrade notes in the Release Notes doc was updated? On Mon, Oct 14, 2013 at 11:07 AM, David Nalley da...@gnsa.us wrote: And just as a heads up, thanks for help from Prasanna and Travis, I've published an updated version of the IG for 4.2, hopefully that at least gets us 'installable'. --David On Thu, Oct 10, 2013 at 2:10 PM, David Nalley da...@gnsa.us wrote: On Thu, Oct 10, 2013 at 1:53 PM, Travis Graham tgra...@tgraham.us wrote: What's an acceptable/expected timeframe for rolling out the published fixes once a patch has made it's way in? Is that something that can be automated after a successful Jenkins run? Travis It depends on the scope of changes. For a document like the release notes, assuming someone already has an updated SVN tree, it shouldn't take more than 30 minutes to update, and it could happen pretty regularly. If it's every document in a single release, that's historically taken the better part of a day. I don't think we'll get away with getting it to happen in an automated fashion, simply because it requires commit access to SVN, which is tied to an individual, which means someone would need to expose their creds, which would be a bad thing. --David -- Andrija Panić -- http://admintweets.com --
Re: Doc Updates
David, Would you mind posting the url for the update you reference? I'm looking at the 4.2 view on buildacloud.com and the last update there was a month ago. So I assume I'm looking in the wrong place. Thanks, Fred On Mon, Oct 14, 2013 at 2:07 PM, David Nalley da...@gnsa.us wrote: And just as a heads up, thanks for help from Prasanna and Travis, I've published an updated version of the IG for 4.2, hopefully that at least gets us 'installable'. --David On Thu, Oct 10, 2013 at 2:10 PM, David Nalley da...@gnsa.us wrote: On Thu, Oct 10, 2013 at 1:53 PM, Travis Graham tgra...@tgraham.us wrote: What's an acceptable/expected timeframe for rolling out the published fixes once a patch has made it's way in? Is that something that can be automated after a successful Jenkins run? Travis It depends on the scope of changes. For a document like the release notes, assuming someone already has an updated SVN tree, it shouldn't take more than 30 minutes to update, and it could happen pretty regularly. If it's every document in a single release, that's historically taken the better part of a day. I don't think we'll get away with getting it to happen in an automated fashion, simply because it requires commit access to SVN, which is tied to an individual, which means someone would need to expose their creds, which would be a bad thing. --David
Re: Doc Updates
Thanks for updating it. Without knowing what to look for in the prepare system vm template section I would not have known that it was updated. Would it make sense to have a date in the header or footer with the last content update date for a page? Also do you know if the upgrade notes in the Release Notes doc was updated? On Mon, Oct 14, 2013 at 11:07 AM, David Nalley da...@gnsa.us wrote: And just as a heads up, thanks for help from Prasanna and Travis, I've published an updated version of the IG for 4.2, hopefully that at least gets us 'installable'. --David On Thu, Oct 10, 2013 at 2:10 PM, David Nalley da...@gnsa.us wrote: On Thu, Oct 10, 2013 at 1:53 PM, Travis Graham tgra...@tgraham.us wrote: What's an acceptable/expected timeframe for rolling out the published fixes once a patch has made it's way in? Is that something that can be automated after a successful Jenkins run? Travis It depends on the scope of changes. For a document like the release notes, assuming someone already has an updated SVN tree, it shouldn't take more than 30 minutes to update, and it could happen pretty regularly. If it's every document in a single release, that's historically taken the better part of a day. I don't think we'll get away with getting it to happen in an automated fashion, simply because it requires commit access to SVN, which is tied to an individual, which means someone would need to expose their creds, which would be a bad thing. --David
Re: Doc Updates
And just as a heads up, thanks for help from Prasanna and Travis, I've published an updated version of the IG for 4.2, hopefully that at least gets us 'installable'. --David On Thu, Oct 10, 2013 at 2:10 PM, David Nalley da...@gnsa.us wrote: On Thu, Oct 10, 2013 at 1:53 PM, Travis Graham tgra...@tgraham.us wrote: What's an acceptable/expected timeframe for rolling out the published fixes once a patch has made it's way in? Is that something that can be automated after a successful Jenkins run? Travis It depends on the scope of changes. For a document like the release notes, assuming someone already has an updated SVN tree, it shouldn't take more than 30 minutes to update, and it could happen pretty regularly. If it's every document in a single release, that's historically taken the better part of a day. I don't think we'll get away with getting it to happen in an automated fashion, simply because it requires commit access to SVN, which is tied to an individual, which means someone would need to expose their creds, which would be a bad thing. --David
Re: Doc Updates
As you find these things, please create an issue in the JIRA. At least there will be a record of what needs fixing. The dispersion of effort and information between the docs and the wiki needs some discussion. To an outsider, the wiki seems to be a place that is used to compensate for the deficiencies and errors in the manuals. That just makes it hard to find the right information. Ron On 10/10/2013 3:11 PM, Fred Messinger wrote: Agreed Carlos. I've spent all day reading said emails and trying to wrangle through this problem myself. How to update the templates is here: https://cwiki.apache.org/confluence/display/CLOUDSTACK/How+to+build+CloudStack# but even getting that to work was an adventure. On Thu, Oct 10, 2013 at 2:44 PM, Carlos Reategui car...@reategui.comwrote: On Thu, Oct 10, 2013 at 10:48 AM, David Nalley da...@gnsa.us wrote: That is how it has been done previously - but we recently moved docs to their own repo to separate the software lifecycle from the docs lifecycle, and we have already had at least one update pushed to the docs post-release. Over the past couple weeks a good percentage of the emails to the list have been caused due to the wrong template URL in the installation docs. I just had a look and they are still pointing to the old templates. Along the same lines the other problem most people have had is not knowing to upgrade the templates when upgrading from 4.1 to 4.2. Just had a look at the docs and that is still not been updated. I would have thought this would have been a high priority to fix and would have been in that first update given the number of people running into these. The goal is to try and keep this up, and I hope to publish another set of updates tomorrow or over the weekend. Bad docs make even the best software unusable IMO. That said, we could use more eyeballs - at least identify the problems for us. Bonus points for fixes. Can you point us to a guide on how to make doc fixes? Is this in git? I though I just saw a reference to SVN in another email in this thread. --David On Wed, Oct 9, 2013 at 4:24 PM, Carlos Reategui create...@gmail.com wrote: It seems like the only way that docs ( http://cloudstack.apache.org/docs/en-US/index.html) are updated is when a release is done. Is it not possible to have these updated otherwise? Waiting for the next patch release of the software so that the docs get updated is causing problems with folks not being able to get CloudStack installed properly and therefore gives them a bad impression of the maturity of CloudStack. It makes no sense to me why there are multiple versions of documents for each of the point releases (currently there is 4.0.0, 4.0.1, 4.0.2, 4.1.0, 4.1.1 and 4.0.2 docs) when the feature set has not changed within each of these. I understand that the docs are built as part of the build and release process but why does that have to impact the rate at which the primary doc site is updated. Can't the patch releases simply update the release notes? Personally I think there should be a single 4.x version of the docs (I would be ok with a 4.0, 4.1 and 4.2 versions too if major features are going to be added to them). Maybe the doc site should have wiki like capabilities so that it can be more easily maintained. ok, I am done ranting... -- Ron Wheeler President Artifact Software Inc email: rwhee...@artifact-software.com skype: ronaldmwheeler phone: 866-970-2435, ext 102
Re: Doc Updates
Agreed Darren, I would like a nightly build, especially of the api docs. The generic docs as well would be fine. there is a jenkins job for those api docs at https://builds.apache.org/job/cloudstack-apidocs-master/ Can I get karma to see if i can direct the artifacts from that somewhere? Or should we use http://jenkins.buildacloud.org/? most of the doc targets are there regards, Daan On Thu, Oct 10, 2013 at 6:18 AM, Darren Shepherd darren.s.sheph...@gmail.com wrote: Is it not possible to just have a master/latest/head/snapshot version of the docs on the web page with the individual release too. I do think it it important to snapshot the documents at the individual point releases and have those available. But just a latest, fresh from git link would be nice. Darren On Wed, Oct 9, 2013 at 7:11 PM, Ron Wheeler rwhee...@artifact-software.com wrote: When the software was released with a number of reported bugs in the docs, it was done with the understanding that the 4.2 docs would be prepared after the release of the software. Ron On 09/10/2013 4:34 PM, Daan Hoogland wrote: Great rant Carlos, You should get it to the dev list. Actually I'll add the dev list in now. It makes sense to update the docs also after a release, when bug in the docs are found these can easily be changed without a full release cycle of the code itself. regards, Daan On Wed, Oct 9, 2013 at 10:24 PM, Carlos Reategui create...@gmail.com wrote: It seems like the only way that docs ( http://cloudstack.apache.org/docs/en-US/index.html) are updated is when a release is done. Is it not possible to have these updated otherwise? Waiting for the next patch release of the software so that the docs get updated is causing problems with folks not being able to get CloudStack installed properly and therefore gives them a bad impression of the maturity of CloudStack. It makes no sense to me why there are multiple versions of documents for each of the point releases (currently there is 4.0.0, 4.0.1, 4.0.2, 4.1.0, 4.1.1 and 4.0.2 docs) when the feature set has not changed within each of these. I understand that the docs are built as part of the build and release process but why does that have to impact the rate at which the primary doc site is updated. Can't the patch releases simply update the release notes? Personally I think there should be a single 4.x version of the docs (I would be ok with a 4.0, 4.1 and 4.2 versions too if major features are going to be added to them). Maybe the doc site should have wiki like capabilities so that it can be more easily maintained. ok, I am done ranting... -- Ron Wheeler President Artifact Software Inc email: rwhee...@artifact-software.com skype: ronaldmwheeler phone: 866-970-2435, ext 102
Re: Doc Updates
jenkins.buildacloud.org, most jobs that the project uses are on buildacloud.org. It's fully under our control and I find it more responsive than builds.a.o On Thu, Oct 10, 2013 at 02:11:01PM +0200, Daan Hoogland wrote: Agreed Darren, I would like a nightly build, especially of the api docs. The generic docs as well would be fine. there is a jenkins job for those api docs at https://builds.apache.org/job/cloudstack-apidocs-master/ Can I get karma to see if i can direct the artifacts from that somewhere? Or should we use http://jenkins.buildacloud.org/? most of the doc targets are there regards, Daan On Thu, Oct 10, 2013 at 6:18 AM, Darren Shepherd darren.s.sheph...@gmail.com wrote: Is it not possible to just have a master/latest/head/snapshot version of the docs on the web page with the individual release too. I do think it it important to snapshot the documents at the individual point releases and have those available. But just a latest, fresh from git link would be nice. Darren On Wed, Oct 9, 2013 at 7:11 PM, Ron Wheeler rwhee...@artifact-software.com wrote: When the software was released with a number of reported bugs in the docs, it was done with the understanding that the 4.2 docs would be prepared after the release of the software. Ron On 09/10/2013 4:34 PM, Daan Hoogland wrote: Great rant Carlos, You should get it to the dev list. Actually I'll add the dev list in now. It makes sense to update the docs also after a release, when bug in the docs are found these can easily be changed without a full release cycle of the code itself. regards, Daan On Wed, Oct 9, 2013 at 10:24 PM, Carlos Reategui create...@gmail.com wrote: It seems like the only way that docs ( http://cloudstack.apache.org/docs/en-US/index.html) are updated is when a release is done. Is it not possible to have these updated otherwise? Waiting for the next patch release of the software so that the docs get updated is causing problems with folks not being able to get CloudStack installed properly and therefore gives them a bad impression of the maturity of CloudStack. It makes no sense to me why there are multiple versions of documents for each of the point releases (currently there is 4.0.0, 4.0.1, 4.0.2, 4.1.0, 4.1.1 and 4.0.2 docs) when the feature set has not changed within each of these. I understand that the docs are built as part of the build and release process but why does that have to impact the rate at which the primary doc site is updated. Can't the patch releases simply update the release notes? Personally I think there should be a single 4.x version of the docs (I would be ok with a 4.0, 4.1 and 4.2 versions too if major features are going to be added to them). Maybe the doc site should have wiki like capabilities so that it can be more easily maintained. ok, I am done ranting... -- Ron Wheeler President Artifact Software Inc email: rwhee...@artifact-software.com skype: ronaldmwheeler phone: 866-970-2435, ext 102 -- Prasanna., Powered by BigRock.com
Re: Doc Updates
That is how it has been done previously - but we recently moved docs to their own repo to separate the software lifecycle from the docs lifecycle, and we have already had at least one update pushed to the docs post-release. The goal is to try and keep this up, and I hope to publish another set of updates tomorrow or over the weekend. Bad docs make even the best software unusable IMO. That said, we could use more eyeballs - at least identify the problems for us. Bonus points for fixes. --David On Wed, Oct 9, 2013 at 4:24 PM, Carlos Reategui create...@gmail.com wrote: It seems like the only way that docs ( http://cloudstack.apache.org/docs/en-US/index.html) are updated is when a release is done. Is it not possible to have these updated otherwise? Waiting for the next patch release of the software so that the docs get updated is causing problems with folks not being able to get CloudStack installed properly and therefore gives them a bad impression of the maturity of CloudStack. It makes no sense to me why there are multiple versions of documents for each of the point releases (currently there is 4.0.0, 4.0.1, 4.0.2, 4.1.0, 4.1.1 and 4.0.2 docs) when the feature set has not changed within each of these. I understand that the docs are built as part of the build and release process but why does that have to impact the rate at which the primary doc site is updated. Can't the patch releases simply update the release notes? Personally I think there should be a single 4.x version of the docs (I would be ok with a 4.0, 4.1 and 4.2 versions too if major features are going to be added to them). Maybe the doc site should have wiki like capabilities so that it can be more easily maintained. ok, I am done ranting...
Re: Doc Updates
What's an acceptable/expected timeframe for rolling out the published fixes once a patch has made it's way in? Is that something that can be automated after a successful Jenkins run? Travis On Oct 10, 2013, at 1:48 PM, David Nalley da...@gnsa.us wrote: That is how it has been done previously - but we recently moved docs to their own repo to separate the software lifecycle from the docs lifecycle, and we have already had at least one update pushed to the docs post-release. The goal is to try and keep this up, and I hope to publish another set of updates tomorrow or over the weekend. Bad docs make even the best software unusable IMO. That said, we could use more eyeballs - at least identify the problems for us. Bonus points for fixes. --David On Wed, Oct 9, 2013 at 4:24 PM, Carlos Reategui create...@gmail.com wrote: It seems like the only way that docs ( http://cloudstack.apache.org/docs/en-US/index.html) are updated is when a release is done. Is it not possible to have these updated otherwise? Waiting for the next patch release of the software so that the docs get updated is causing problems with folks not being able to get CloudStack installed properly and therefore gives them a bad impression of the maturity of CloudStack. It makes no sense to me why there are multiple versions of documents for each of the point releases (currently there is 4.0.0, 4.0.1, 4.0.2, 4.1.0, 4.1.1 and 4.0.2 docs) when the feature set has not changed within each of these. I understand that the docs are built as part of the build and release process but why does that have to impact the rate at which the primary doc site is updated. Can't the patch releases simply update the release notes? Personally I think there should be a single 4.x version of the docs (I would be ok with a 4.0, 4.1 and 4.2 versions too if major features are going to be added to them). Maybe the doc site should have wiki like capabilities so that it can be more easily maintained. ok, I am done ranting...
Re: Doc Updates
On Thu, Oct 10, 2013 at 1:53 PM, Travis Graham tgra...@tgraham.us wrote: What's an acceptable/expected timeframe for rolling out the published fixes once a patch has made it's way in? Is that something that can be automated after a successful Jenkins run? Travis It depends on the scope of changes. For a document like the release notes, assuming someone already has an updated SVN tree, it shouldn't take more than 30 minutes to update, and it could happen pretty regularly. If it's every document in a single release, that's historically taken the better part of a day. I don't think we'll get away with getting it to happen in an automated fashion, simply because it requires commit access to SVN, which is tied to an individual, which means someone would need to expose their creds, which would be a bad thing. --David
Re: Doc Updates
On Thu, Oct 10, 2013 at 10:48 AM, David Nalley da...@gnsa.us wrote: That is how it has been done previously - but we recently moved docs to their own repo to separate the software lifecycle from the docs lifecycle, and we have already had at least one update pushed to the docs post-release. Over the past couple weeks a good percentage of the emails to the list have been caused due to the wrong template URL in the installation docs. I just had a look and they are still pointing to the old templates. Along the same lines the other problem most people have had is not knowing to upgrade the templates when upgrading from 4.1 to 4.2. Just had a look at the docs and that is still not been updated. I would have thought this would have been a high priority to fix and would have been in that first update given the number of people running into these. The goal is to try and keep this up, and I hope to publish another set of updates tomorrow or over the weekend. Bad docs make even the best software unusable IMO. That said, we could use more eyeballs - at least identify the problems for us. Bonus points for fixes. Can you point us to a guide on how to make doc fixes? Is this in git? I though I just saw a reference to SVN in another email in this thread. --David On Wed, Oct 9, 2013 at 4:24 PM, Carlos Reategui create...@gmail.com wrote: It seems like the only way that docs ( http://cloudstack.apache.org/docs/en-US/index.html) are updated is when a release is done. Is it not possible to have these updated otherwise? Waiting for the next patch release of the software so that the docs get updated is causing problems with folks not being able to get CloudStack installed properly and therefore gives them a bad impression of the maturity of CloudStack. It makes no sense to me why there are multiple versions of documents for each of the point releases (currently there is 4.0.0, 4.0.1, 4.0.2, 4.1.0, 4.1.1 and 4.0.2 docs) when the feature set has not changed within each of these. I understand that the docs are built as part of the build and release process but why does that have to impact the rate at which the primary doc site is updated. Can't the patch releases simply update the release notes? Personally I think there should be a single 4.x version of the docs (I would be ok with a 4.0, 4.1 and 4.2 versions too if major features are going to be added to them). Maybe the doc site should have wiki like capabilities so that it can be more easily maintained. ok, I am done ranting...
Re: Doc Updates
Agreed Carlos. I've spent all day reading said emails and trying to wrangle through this problem myself. How to update the templates is here: https://cwiki.apache.org/confluence/display/CLOUDSTACK/How+to+build+CloudStack# but even getting that to work was an adventure. On Thu, Oct 10, 2013 at 2:44 PM, Carlos Reategui car...@reategui.comwrote: On Thu, Oct 10, 2013 at 10:48 AM, David Nalley da...@gnsa.us wrote: That is how it has been done previously - but we recently moved docs to their own repo to separate the software lifecycle from the docs lifecycle, and we have already had at least one update pushed to the docs post-release. Over the past couple weeks a good percentage of the emails to the list have been caused due to the wrong template URL in the installation docs. I just had a look and they are still pointing to the old templates. Along the same lines the other problem most people have had is not knowing to upgrade the templates when upgrading from 4.1 to 4.2. Just had a look at the docs and that is still not been updated. I would have thought this would have been a high priority to fix and would have been in that first update given the number of people running into these. The goal is to try and keep this up, and I hope to publish another set of updates tomorrow or over the weekend. Bad docs make even the best software unusable IMO. That said, we could use more eyeballs - at least identify the problems for us. Bonus points for fixes. Can you point us to a guide on how to make doc fixes? Is this in git? I though I just saw a reference to SVN in another email in this thread. --David On Wed, Oct 9, 2013 at 4:24 PM, Carlos Reategui create...@gmail.com wrote: It seems like the only way that docs ( http://cloudstack.apache.org/docs/en-US/index.html) are updated is when a release is done. Is it not possible to have these updated otherwise? Waiting for the next patch release of the software so that the docs get updated is causing problems with folks not being able to get CloudStack installed properly and therefore gives them a bad impression of the maturity of CloudStack. It makes no sense to me why there are multiple versions of documents for each of the point releases (currently there is 4.0.0, 4.0.1, 4.0.2, 4.1.0, 4.1.1 and 4.0.2 docs) when the feature set has not changed within each of these. I understand that the docs are built as part of the build and release process but why does that have to impact the rate at which the primary doc site is updated. Can't the patch releases simply update the release notes? Personally I think there should be a single 4.x version of the docs (I would be ok with a 4.0, 4.1 and 4.2 versions too if major features are going to be added to them). Maybe the doc site should have wiki like capabilities so that it can be more easily maintained. ok, I am done ranting...
Re: Doc Updates
Great rant Carlos, You should get it to the dev list. Actually I'll add the dev list in now. It makes sense to update the docs also after a release, when bug in the docs are found these can easily be changed without a full release cycle of the code itself. regards, Daan On Wed, Oct 9, 2013 at 10:24 PM, Carlos Reategui create...@gmail.com wrote: It seems like the only way that docs ( http://cloudstack.apache.org/docs/en-US/index.html) are updated is when a release is done. Is it not possible to have these updated otherwise? Waiting for the next patch release of the software so that the docs get updated is causing problems with folks not being able to get CloudStack installed properly and therefore gives them a bad impression of the maturity of CloudStack. It makes no sense to me why there are multiple versions of documents for each of the point releases (currently there is 4.0.0, 4.0.1, 4.0.2, 4.1.0, 4.1.1 and 4.0.2 docs) when the feature set has not changed within each of these. I understand that the docs are built as part of the build and release process but why does that have to impact the rate at which the primary doc site is updated. Can't the patch releases simply update the release notes? Personally I think there should be a single 4.x version of the docs (I would be ok with a 4.0, 4.1 and 4.2 versions too if major features are going to be added to them). Maybe the doc site should have wiki like capabilities so that it can be more easily maintained. ok, I am done ranting...
RE: Doc Updates
+1 on this. I find management hard to please when I persuade changing to a new technology only to have issues related to documentation. This prolongs deployment and doesn't help with the already difficult management decision. It took us a month to switch to CloudStack and almost a week to begin defending the choice because of outdated documentation. This was of course before the donation to apache, since then it's been a lot easier and management isn't so concerned. but none the less, publicly facing documentation, I feel, should be kept current, to include bug fixes. Chris Ryan Harmonia Holdings Group, LLC 404 People Place, Suite 402 Charlottesville, VA 22911 Office: (434) 244-4002 -Original Message- From: Daan Hoogland [mailto:daan.hoogl...@gmail.com] Sent: Wednesday, October 09, 2013 4:34 PM To: users@cloudstack.apache.org; car...@reategui.com; dev Subject: Re: Doc Updates Great rant Carlos, You should get it to the dev list. Actually I'll add the dev list in now. It makes sense to update the docs also after a release, when bug in the docs are found these can easily be changed without a full release cycle of the code itself. regards, Daan On Wed, Oct 9, 2013 at 10:24 PM, Carlos Reategui create...@gmail.com wrote: It seems like the only way that docs ( http://cloudstack.apache.org/docs/en-US/index.html) are updated is when a release is done. Is it not possible to have these updated otherwise? Waiting for the next patch release of the software so that the docs get updated is causing problems with folks not being able to get CloudStack installed properly and therefore gives them a bad impression of the maturity of CloudStack. It makes no sense to me why there are multiple versions of documents for each of the point releases (currently there is 4.0.0, 4.0.1, 4.0.2, 4.1.0, 4.1.1 and 4.0.2 docs) when the feature set has not changed within each of these. I understand that the docs are built as part of the build and release process but why does that have to impact the rate at which the primary doc site is updated. Can't the patch releases simply update the release notes? Personally I think there should be a single 4.x version of the docs (I would be ok with a 4.0, 4.1 and 4.2 versions too if major features are going to be added to them). Maybe the doc site should have wiki like capabilities so that it can be more easily maintained. ok, I am done ranting...
Re: Doc Updates
I see at least 1 topic for the cloudstack collab. +1 Sent from my iPhone On 9 okt. 2013, at 23:01, Christopher M. Ryan cr...@harmonia.com wrote: +1 on this. I find management hard to please when I persuade changing to a new technology only to have issues related to documentation. This prolongs deployment and doesn't help with the already difficult management decision. It took us a month to switch to CloudStack and almost a week to begin defending the choice because of outdated documentation. This was of course before the donation to apache, since then it's been a lot easier and management isn't so concerned. but none the less, publicly facing documentation, I feel, should be kept current, to include bug fixes. Chris Ryan Harmonia Holdings Group, LLC 404 People Place, Suite 402 Charlottesville, VA 22911 Office: (434) 244-4002 -Original Message- From: Daan Hoogland [mailto:daan.hoogl...@gmail.com] Sent: Wednesday, October 09, 2013 4:34 PM To: users@cloudstack.apache.org; car...@reategui.com; dev Subject: Re: Doc Updates Great rant Carlos, You should get it to the dev list. Actually I'll add the dev list in now. It makes sense to update the docs also after a release, when bug in the docs are found these can easily be changed without a full release cycle of the code itself. regards, Daan On Wed, Oct 9, 2013 at 10:24 PM, Carlos Reategui create...@gmail.com wrote: It seems like the only way that docs ( http://cloudstack.apache.org/docs/en-US/index.html) are updated is when a release is done. Is it not possible to have these updated otherwise? Waiting for the next patch release of the software so that the docs get updated is causing problems with folks not being able to get CloudStack installed properly and therefore gives them a bad impression of the maturity of CloudStack. It makes no sense to me why there are multiple versions of documents for each of the point releases (currently there is 4.0.0, 4.0.1, 4.0.2, 4.1.0, 4.1.1 and 4.0.2 docs) when the feature set has not changed within each of these. I understand that the docs are built as part of the build and release process but why does that have to impact the rate at which the primary doc site is updated. Can't the patch releases simply update the release notes? Personally I think there should be a single 4.x version of the docs (I would be ok with a 4.0, 4.1 and 4.2 versions too if major features are going to be added to them). Maybe the doc site should have wiki like capabilities so that it can be more easily maintained. ok, I am done ranting...
Re: Doc Updates
The docs have recently been moved into their main repo. This potentially means that we are heading towards documentation releases on a different cycle than the code release. We are not there yet but it's in the works, anyone interested and willing to contribute patches and ideas should register to the dev list and participate in [DOCS] threads. -sebastien On Oct 9, 2013, at 5:25 PM, Harm Boertien hboert...@schubergphilis.com wrote: I see at least 1 topic for the cloudstack collab. +1 Sent from my iPhone On 9 okt. 2013, at 23:01, Christopher M. Ryan cr...@harmonia.com wrote: +1 on this. I find management hard to please when I persuade changing to a new technology only to have issues related to documentation. This prolongs deployment and doesn't help with the already difficult management decision. It took us a month to switch to CloudStack and almost a week to begin defending the choice because of outdated documentation. This was of course before the donation to apache, since then it's been a lot easier and management isn't so concerned. but none the less, publicly facing documentation, I feel, should be kept current, to include bug fixes. Chris Ryan Harmonia Holdings Group, LLC 404 People Place, Suite 402 Charlottesville, VA 22911 Office: (434) 244-4002 -Original Message- From: Daan Hoogland [mailto:daan.hoogl...@gmail.com] Sent: Wednesday, October 09, 2013 4:34 PM To: users@cloudstack.apache.org; car...@reategui.com; dev Subject: Re: Doc Updates Great rant Carlos, You should get it to the dev list. Actually I'll add the dev list in now. It makes sense to update the docs also after a release, when bug in the docs are found these can easily be changed without a full release cycle of the code itself. regards, Daan On Wed, Oct 9, 2013 at 10:24 PM, Carlos Reategui create...@gmail.com wrote: It seems like the only way that docs ( http://cloudstack.apache.org/docs/en-US/index.html) are updated is when a release is done. Is it not possible to have these updated otherwise? Waiting for the next patch release of the software so that the docs get updated is causing problems with folks not being able to get CloudStack installed properly and therefore gives them a bad impression of the maturity of CloudStack. It makes no sense to me why there are multiple versions of documents for each of the point releases (currently there is 4.0.0, 4.0.1, 4.0.2, 4.1.0, 4.1.1 and 4.0.2 docs) when the feature set has not changed within each of these. I understand that the docs are built as part of the build and release process but why does that have to impact the rate at which the primary doc site is updated. Can't the patch releases simply update the release notes? Personally I think there should be a single 4.x version of the docs (I would be ok with a 4.0, 4.1 and 4.2 versions too if major features are going to be added to them). Maybe the doc site should have wiki like capabilities so that it can be more easily maintained. ok, I am done ranting...
Re: Doc Updates
When the software was released with a number of reported bugs in the docs, it was done with the understanding that the 4.2 docs would be prepared after the release of the software. Ron On 09/10/2013 4:34 PM, Daan Hoogland wrote: Great rant Carlos, You should get it to the dev list. Actually I'll add the dev list in now. It makes sense to update the docs also after a release, when bug in the docs are found these can easily be changed without a full release cycle of the code itself. regards, Daan On Wed, Oct 9, 2013 at 10:24 PM, Carlos Reategui create...@gmail.com wrote: It seems like the only way that docs ( http://cloudstack.apache.org/docs/en-US/index.html) are updated is when a release is done. Is it not possible to have these updated otherwise? Waiting for the next patch release of the software so that the docs get updated is causing problems with folks not being able to get CloudStack installed properly and therefore gives them a bad impression of the maturity of CloudStack. It makes no sense to me why there are multiple versions of documents for each of the point releases (currently there is 4.0.0, 4.0.1, 4.0.2, 4.1.0, 4.1.1 and 4.0.2 docs) when the feature set has not changed within each of these. I understand that the docs are built as part of the build and release process but why does that have to impact the rate at which the primary doc site is updated. Can't the patch releases simply update the release notes? Personally I think there should be a single 4.x version of the docs (I would be ok with a 4.0, 4.1 and 4.2 versions too if major features are going to be added to them). Maybe the doc site should have wiki like capabilities so that it can be more easily maintained. ok, I am done ranting... -- Ron Wheeler President Artifact Software Inc email: rwhee...@artifact-software.com skype: ronaldmwheeler phone: 866-970-2435, ext 102
Re: Doc Updates
Is it not possible to just have a master/latest/head/snapshot version of the docs on the web page with the individual release too. I do think it it important to snapshot the documents at the individual point releases and have those available. But just a latest, fresh from git link would be nice. Darren On Wed, Oct 9, 2013 at 7:11 PM, Ron Wheeler rwhee...@artifact-software.com wrote: When the software was released with a number of reported bugs in the docs, it was done with the understanding that the 4.2 docs would be prepared after the release of the software. Ron On 09/10/2013 4:34 PM, Daan Hoogland wrote: Great rant Carlos, You should get it to the dev list. Actually I'll add the dev list in now. It makes sense to update the docs also after a release, when bug in the docs are found these can easily be changed without a full release cycle of the code itself. regards, Daan On Wed, Oct 9, 2013 at 10:24 PM, Carlos Reategui create...@gmail.com wrote: It seems like the only way that docs ( http://cloudstack.apache.org/docs/en-US/index.html) are updated is when a release is done. Is it not possible to have these updated otherwise? Waiting for the next patch release of the software so that the docs get updated is causing problems with folks not being able to get CloudStack installed properly and therefore gives them a bad impression of the maturity of CloudStack. It makes no sense to me why there are multiple versions of documents for each of the point releases (currently there is 4.0.0, 4.0.1, 4.0.2, 4.1.0, 4.1.1 and 4.0.2 docs) when the feature set has not changed within each of these. I understand that the docs are built as part of the build and release process but why does that have to impact the rate at which the primary doc site is updated. Can't the patch releases simply update the release notes? Personally I think there should be a single 4.x version of the docs (I would be ok with a 4.0, 4.1 and 4.2 versions too if major features are going to be added to them). Maybe the doc site should have wiki like capabilities so that it can be more easily maintained. ok, I am done ranting... -- Ron Wheeler President Artifact Software Inc email: rwhee...@artifact-software.com skype: ronaldmwheeler phone: 866-970-2435, ext 102
