Re: Pointing docs to edge
Okay, so here are the current proposals for handling Ray's issue (thanks Ray!): 1. Update docs at commit-time and release-time. At commit-time, documentation changes can be marked with coming soon, or removed in next release, or whatever the relevant message is. At release-time, docs are further updated to remove these sub-messages. 2. Use CSS to do the manual marking in proposal 1. We could also use it to hide certain documentation changes until release. 3. Create a docs branch for each releasable component. Whenever a component is released, merge that branch into master. Does anyone feel strongly about any of these or have another suggestion? On Fri, Jul 11, 2014 at 2:57 PM, Andrew Grieve agri...@chromium.org wrote: Good point Ray. Another option would be to create a branch-per-component e.g. tools, android, ios, etc. that changes go into, and then merge into master from the branch that corresponds to the release that is happening On Fri, Jul 11, 2014 at 2:02 PM, Michal Mocny mmo...@chromium.org wrote: Ray, but I thought we always wanted more cowbell? Sorry, had to. I agree with Ray here, but I would also want to see latest fixes to docs that apply to released version. Suggestion: rely on discipline to markup documentation changes which only apply to development versions? e.g. div class=available-in-4.0 Now with more ---cowbell! /div And part of release instructions is to change styling from looking scary/experimental to looking ordinary? -Michal On Fri, Jul 11, 2014 at 1:51 PM, Ray Camden rayca...@adobe.com wrote: Ok, so let me rephrase then. Imagine the next version of the CLI adds cowbell support: cordova cowbell --epic but this is NOT in the release version. If I go to docs.cordova.io, click on The Command Line Interface, will I see cowbell documented? If so, I think that is a mistake. From: agri...@google.com agri...@google.com on behalf of Andrew Grieve agri...@chromium.org Sent: Friday, July 11, 2014 11:39 AM To: dev Subject: Re: Pointing docs to edge Yeah, plugin docs are already gone from docs.cordova.io. This change is strictly for guides platform docs. The main motivation here is that it doesn't make sense to have versioned docs if platform versions diverge anyways. It actually already makes little sense for the tools guides, since they are released more often the platforms. On Fri, Jul 11, 2014 at 12:36 PM, Max Woghiren m...@chromium.org wrote: My understanding is that plugin docs live in plugin repos and will be versioned alongside the plugins themselves. They'll be removed from docs.cordova.io. On Fri, Jul 11, 2014 at 11:49 AM, Ray Camden rayca...@adobe.com wrote: Is edge what people use when they get the latest version of cordova or a plugin? If not, I'd strongly argue against it. If I download the Camera plugin, I expect the default docs to match whats shipped in that version. From: m...@google.com m...@google.com on behalf of Max Woghiren m...@chromium.org Sent: Friday, July 11, 2014 10:46 AM To: dev Subject: Pointing docs to edge Just wanted to bring back this conversation—how does everyone feel about switching docs.cordova.io to point to edge? There has been some discussion about cutting versioned docs after 3.5.0, and we're approaching a good time to do it. :)
Re: Pointing docs to edge
I think we can also use a combination of these. For small changes where it makes sense, just push to master and be conscious of its effect on the current tools release out in the wild. If the change is significant and inline documentation gets hairy, just create a branch. A side benefit of doing more and master and getting it into the eyes of users is earlier feedback on what's coming up. Either way, whatever we chose, lowering process overhead is what we need right now. Lets just do what feels natural and leads for devs actually focusing on docs! On Mon, Jul 14, 2014 at 11:27 AM, Max Woghiren m...@chromium.org wrote: Okay, so here are the current proposals for handling Ray's issue (thanks Ray!): 1. Update docs at commit-time and release-time. At commit-time, documentation changes can be marked with coming soon, or removed in next release, or whatever the relevant message is. At release-time, docs are further updated to remove these sub-messages. 2. Use CSS to do the manual marking in proposal 1. We could also use it to hide certain documentation changes until release. 3. Create a docs branch for each releasable component. Whenever a component is released, merge that branch into master. Does anyone feel strongly about any of these or have another suggestion? On Fri, Jul 11, 2014 at 2:57 PM, Andrew Grieve agri...@chromium.org wrote: Good point Ray. Another option would be to create a branch-per-component e.g. tools, android, ios, etc. that changes go into, and then merge into master from the branch that corresponds to the release that is happening On Fri, Jul 11, 2014 at 2:02 PM, Michal Mocny mmo...@chromium.org wrote: Ray, but I thought we always wanted more cowbell? Sorry, had to. I agree with Ray here, but I would also want to see latest fixes to docs that apply to released version. Suggestion: rely on discipline to markup documentation changes which only apply to development versions? e.g. div class=available-in-4.0 Now with more ---cowbell! /div And part of release instructions is to change styling from looking scary/experimental to looking ordinary? -Michal On Fri, Jul 11, 2014 at 1:51 PM, Ray Camden rayca...@adobe.com wrote: Ok, so let me rephrase then. Imagine the next version of the CLI adds cowbell support: cordova cowbell --epic but this is NOT in the release version. If I go to docs.cordova.io, click on The Command Line Interface, will I see cowbell documented? If so, I think that is a mistake. From: agri...@google.com agri...@google.com on behalf of Andrew Grieve agri...@chromium.org Sent: Friday, July 11, 2014 11:39 AM To: dev Subject: Re: Pointing docs to edge Yeah, plugin docs are already gone from docs.cordova.io. This change is strictly for guides platform docs. The main motivation here is that it doesn't make sense to have versioned docs if platform versions diverge anyways. It actually already makes little sense for the tools guides, since they are released more often the platforms. On Fri, Jul 11, 2014 at 12:36 PM, Max Woghiren m...@chromium.org wrote: My understanding is that plugin docs live in plugin repos and will be versioned alongside the plugins themselves. They'll be removed from docs.cordova.io. On Fri, Jul 11, 2014 at 11:49 AM, Ray Camden rayca...@adobe.com wrote: Is edge what people use when they get the latest version of cordova or a plugin? If not, I'd strongly argue against it. If I download the Camera plugin, I expect the default docs to match whats shipped in that version. From: m...@google.com m...@google.com on behalf of Max Woghiren m...@chromium.org Sent: Friday, July 11, 2014 10:46 AM To: dev Subject: Pointing docs to edge Just wanted to bring back this conversation—how does everyone feel about switching docs.cordova.io to point to edge? There has been some discussion about cutting versioned docs after 3.5.0, and we're approaching a good time to do it. :)
RE: Pointing docs to edge
Personally I'd rather not have any coming soon paragraphs in the doc text. As a user, if I'm at the docs, I don't care what is coming next. I'm trying to solve a problem I have *now*, or trying to build now. Anything that is coming soon is a distractor. Do I feel strongly about it? No, but I'd vote against it being in the docs at all. Stuff like that should definitely be communicated to users - via the Cordova blog perhaps - but not in the mainline docs. From: m...@google.com m...@google.com on behalf of Max Woghiren m...@chromium.org Sent: Monday, July 14, 2014 10:27 AM To: dev Subject: Re: Pointing docs to edge Okay, so here are the current proposals for handling Ray's issue (thanks Ray!): 1. Update docs at commit-time and release-time. At commit-time, documentation changes can be marked with coming soon, or removed in next release, or whatever the relevant message is. At release-time, docs are further updated to remove these sub-messages. 2. Use CSS to do the manual marking in proposal 1. We could also use it to
Re: Pointing docs to edge
I agree. I think 3 is my preferred option; I think it lends itself best to a sustainable and straightforward workflow. Docs fixes relevant to the current release of the CLI and each platform can be committed directly to master. Unreleased changes can be committed to the appropriate branch, and we can add the merging of the branch as a step in the release process. On Mon, Jul 14, 2014 at 1:06 PM, Ray Camden rayca...@adobe.com wrote: Personally I'd rather not have any coming soon paragraphs in the doc text. As a user, if I'm at the docs, I don't care what is coming next. I'm trying to solve a problem I have *now*, or trying to build now. Anything that is coming soon is a distractor. Do I feel strongly about it? No, but I'd vote against it being in the docs at all. Stuff like that should definitely be communicated to users - via the Cordova blog perhaps - but not in the mainline docs. From: m...@google.com m...@google.com on behalf of Max Woghiren m...@chromium.org Sent: Monday, July 14, 2014 10:27 AM To: dev Subject: Re: Pointing docs to edge Okay, so here are the current proposals for handling Ray's issue (thanks Ray!): 1. Update docs at commit-time and release-time. At commit-time, documentation changes can be marked with coming soon, or removed in next release, or whatever the relevant message is. At release-time, docs are further updated to remove these sub-messages. 2. Use CSS to do the manual marking in proposal 1. We could also use it to
Re: Pointing docs to edge
I would prefer to have the 'coming soon' stuff more visible. I like the idea that when looking for how to do something, its easy to see improvements that have already landed - and I can possibly get just by grabbing a bleeding edge plugin/tool. On Mon, Jul 14, 2014 at 1:25 PM, Max Woghiren m...@chromium.org wrote: I agree. I think 3 is my preferred option; I think it lends itself best to a sustainable and straightforward workflow. Docs fixes relevant to the current release of the CLI and each platform can be committed directly to master. Unreleased changes can be committed to the appropriate branch, and we can add the merging of the branch as a step in the release process. On Mon, Jul 14, 2014 at 1:06 PM, Ray Camden rayca...@adobe.com wrote: Personally I'd rather not have any coming soon paragraphs in the doc text. As a user, if I'm at the docs, I don't care what is coming next. I'm trying to solve a problem I have *now*, or trying to build now. Anything that is coming soon is a distractor. Do I feel strongly about it? No, but I'd vote against it being in the docs at all. Stuff like that should definitely be communicated to users - via the Cordova blog perhaps - but not in the mainline docs. From: m...@google.com m...@google.com on behalf of Max Woghiren m...@chromium.org Sent: Monday, July 14, 2014 10:27 AM To: dev Subject: Re: Pointing docs to edge Okay, so here are the current proposals for handling Ray's issue (thanks Ray!): 1. Update docs at commit-time and release-time. At commit-time, documentation changes can be marked with coming soon, or removed in next release, or whatever the relevant message is. At release-time, docs are further updated to remove these sub-messages. 2. Use CSS to do the manual marking in proposal 1. We could also use it to
Re: Pointing docs to edge
think that sort of thing belongs to a preview blog post written by the person promising it will land not our canonical docs On Mon, Jul 14, 2014 at 10:30 AM, David Kemp drk...@chromium.org wrote: I would prefer to have the 'coming soon' stuff more visible. I like the idea that when looking for how to do something, its easy to see improvements that have already landed - and I can possibly get just by grabbing a bleeding edge plugin/tool. On Mon, Jul 14, 2014 at 1:25 PM, Max Woghiren m...@chromium.org wrote: I agree. I think 3 is my preferred option; I think it lends itself best to a sustainable and straightforward workflow. Docs fixes relevant to the current release of the CLI and each platform can be committed directly to master. Unreleased changes can be committed to the appropriate branch, and we can add the merging of the branch as a step in the release process. On Mon, Jul 14, 2014 at 1:06 PM, Ray Camden rayca...@adobe.com wrote: Personally I'd rather not have any coming soon paragraphs in the doc text. As a user, if I'm at the docs, I don't care what is coming next. I'm trying to solve a problem I have *now*, or trying to build now. Anything that is coming soon is a distractor. Do I feel strongly about it? No, but I'd vote against it being in the docs at all. Stuff like that should definitely be communicated to users - via the Cordova blog perhaps - but not in the mainline docs. From: m...@google.com m...@google.com on behalf of Max Woghiren m...@chromium.org Sent: Monday, July 14, 2014 10:27 AM To: dev Subject: Re: Pointing docs to edge Okay, so here are the current proposals for handling Ray's issue (thanks Ray!): 1. Update docs at commit-time and release-time. At commit-time, documentation changes can be marked with coming soon, or removed in next release, or whatever the relevant message is. At release-time, docs are further updated to remove these sub-messages. 2. Use CSS to do the manual marking in proposal 1. We could also use it to
Re: Pointing docs to edge
There's probably a better place for that information. Also, in practice, you can imagine how coming soon documentation could be kind of clunky, especially in cases where it's just a behavior change (right now, X does Y and Z; soon it will do K as well, and M instead of Y). I'm sure such changes could be worded more nicely, but that's maybe an unfortunate concern to pin on someone who's making the change. Saying make the documentation change in the relevant branch instead of find a way to neatly explain that the change is coming soon would probably do a better job of encouraging documentation maintenance. On Mon, Jul 14, 2014 at 1:30 PM, David Kemp drk...@chromium.org wrote: I would prefer to have the 'coming soon' stuff more visible. I like the idea that when looking for how to do something, its easy to see improvements that have already landed - and I can possibly get just by grabbing a bleeding edge plugin/tool. On Mon, Jul 14, 2014 at 1:25 PM, Max Woghiren m...@chromium.org wrote: I agree. I think 3 is my preferred option; I think it lends itself best to a sustainable and straightforward workflow. Docs fixes relevant to the current release of the CLI and each platform can be committed directly to master. Unreleased changes can be committed to the appropriate branch, and we can add the merging of the branch as a step in the release process. On Mon, Jul 14, 2014 at 1:06 PM, Ray Camden rayca...@adobe.com wrote: Personally I'd rather not have any coming soon paragraphs in the doc text. As a user, if I'm at the docs, I don't care what is coming next. I'm trying to solve a problem I have *now*, or trying to build now. Anything that is coming soon is a distractor. Do I feel strongly about it? No, but I'd vote against it being in the docs at all. Stuff like that should definitely be communicated to users - via the Cordova blog perhaps - but not in the mainline docs. From: m...@google.com m...@google.com on behalf of Max Woghiren m...@chromium.org Sent: Monday, July 14, 2014 10:27 AM To: dev Subject: Re: Pointing docs to edge Okay, so here are the current proposals for handling Ray's issue (thanks Ray!): 1. Update docs at commit-time and release-time. At commit-time, documentation changes can be marked with coming soon, or removed in next release, or whatever the relevant message is. At release-time, docs are further updated to remove these sub-messages. 2. Use CSS to do the manual marking in proposal 1. We could also use it to
RE: Pointing docs to edge
Is edge what people use when they get the latest version of cordova or a plugin? If not, I'd strongly argue against it. If I download the Camera plugin, I expect the default docs to match whats shipped in that version. From: m...@google.com m...@google.com on behalf of Max Woghiren m...@chromium.org Sent: Friday, July 11, 2014 10:46 AM To: dev Subject: Pointing docs to edge Just wanted to bring back this conversation—how does everyone feel about switching docs.cordova.io to point to edge? There has been some discussion about cutting versioned docs after 3.5.0, and we're approaching a good time to do it. :)
Re: Pointing docs to edge
Yeah, plugin docs are already gone from docs.cordova.io. This change is strictly for guides platform docs. The main motivation here is that it doesn't make sense to have versioned docs if platform versions diverge anyways. It actually already makes little sense for the tools guides, since they are released more often the platforms. On Fri, Jul 11, 2014 at 12:36 PM, Max Woghiren m...@chromium.org wrote: My understanding is that plugin docs live in plugin repos and will be versioned alongside the plugins themselves. They'll be removed from docs.cordova.io. On Fri, Jul 11, 2014 at 11:49 AM, Ray Camden rayca...@adobe.com wrote: Is edge what people use when they get the latest version of cordova or a plugin? If not, I'd strongly argue against it. If I download the Camera plugin, I expect the default docs to match whats shipped in that version. From: m...@google.com m...@google.com on behalf of Max Woghiren m...@chromium.org Sent: Friday, July 11, 2014 10:46 AM To: dev Subject: Pointing docs to edge Just wanted to bring back this conversation—how does everyone feel about switching docs.cordova.io to point to edge? There has been some discussion about cutting versioned docs after 3.5.0, and we're approaching a good time to do it. :)
Re: Pointing docs to edge
My understanding is that plugin docs live in plugin repos and will be versioned alongside the plugins themselves. They'll be removed from docs.cordova.io. On Fri, Jul 11, 2014 at 11:49 AM, Ray Camden rayca...@adobe.com wrote: Is edge what people use when they get the latest version of cordova or a plugin? If not, I'd strongly argue against it. If I download the Camera plugin, I expect the default docs to match whats shipped in that version. From: m...@google.com m...@google.com on behalf of Max Woghiren m...@chromium.org Sent: Friday, July 11, 2014 10:46 AM To: dev Subject: Pointing docs to edge Just wanted to bring back this conversation—how does everyone feel about switching docs.cordova.io to point to edge? There has been some discussion about cutting versioned docs after 3.5.0, and we're approaching a good time to do it. :)
Re: Pointing docs to edge
Yes, Plugin APIs links to a list of github docs. On Fri, Jul 11, 2014 at 12:39 PM, Andrew Grieve agri...@chromium.org wrote: Yeah, plugin docs are already gone from docs.cordova.io. This change is strictly for guides platform docs. The main motivation here is that it doesn't make sense to have versioned docs if platform versions diverge anyways. It actually already makes little sense for the tools guides, since they are released more often the platforms. On Fri, Jul 11, 2014 at 12:36 PM, Max Woghiren m...@chromium.org wrote: My understanding is that plugin docs live in plugin repos and will be versioned alongside the plugins themselves. They'll be removed from docs.cordova.io. On Fri, Jul 11, 2014 at 11:49 AM, Ray Camden rayca...@adobe.com wrote: Is edge what people use when they get the latest version of cordova or a plugin? If not, I'd strongly argue against it. If I download the Camera plugin, I expect the default docs to match whats shipped in that version. From: m...@google.com m...@google.com on behalf of Max Woghiren m...@chromium.org Sent: Friday, July 11, 2014 10:46 AM To: dev Subject: Pointing docs to edge Just wanted to bring back this conversation—how does everyone feel about switching docs.cordova.io to point to edge? There has been some discussion about cutting versioned docs after 3.5.0, and we're approaching a good time to do it. :)
RE: Pointing docs to edge
Ok, so let me rephrase then. Imagine the next version of the CLI adds cowbell support: cordova cowbell --epic but this is NOT in the release version. If I go to docs.cordova.io, click on The Command Line Interface, will I see cowbell documented? If so, I think that is a mistake. From: agri...@google.com agri...@google.com on behalf of Andrew Grieve agri...@chromium.org Sent: Friday, July 11, 2014 11:39 AM To: dev Subject: Re: Pointing docs to edge Yeah, plugin docs are already gone from docs.cordova.io. This change is strictly for guides platform docs. The main motivation here is that it doesn't make sense to have versioned docs if platform versions diverge anyways. It actually already makes little sense for the tools guides, since they are released more often the platforms. On Fri, Jul 11, 2014 at 12:36 PM, Max Woghiren m...@chromium.org wrote: My understanding is that plugin docs live in plugin repos and will be versioned alongside the plugins themselves. They'll be removed from docs.cordova.io. On Fri, Jul 11, 2014 at 11:49 AM, Ray Camden rayca...@adobe.com wrote: Is edge what people use when they get the latest version of cordova or a plugin? If not, I'd strongly argue against it. If I download the Camera plugin, I expect the default docs to match whats shipped in that version. From: m...@google.com m...@google.com on behalf of Max Woghiren m...@chromium.org Sent: Friday, July 11, 2014 10:46 AM To: dev Subject: Pointing docs to edge Just wanted to bring back this conversation—how does everyone feel about switching docs.cordova.io to point to edge? There has been some discussion about cutting versioned docs after 3.5.0, and we're approaching a good time to do it. :)
Re: Pointing docs to edge
Ray, but I thought we always wanted more cowbell? Sorry, had to. I agree with Ray here, but I would also want to see latest fixes to docs that apply to released version. Suggestion: rely on discipline to markup documentation changes which only apply to development versions? e.g. div class=available-in-4.0 Now with more ---cowbell! /div And part of release instructions is to change styling from looking scary/experimental to looking ordinary? -Michal On Fri, Jul 11, 2014 at 1:51 PM, Ray Camden rayca...@adobe.com wrote: Ok, so let me rephrase then. Imagine the next version of the CLI adds cowbell support: cordova cowbell --epic but this is NOT in the release version. If I go to docs.cordova.io, click on The Command Line Interface, will I see cowbell documented? If so, I think that is a mistake. From: agri...@google.com agri...@google.com on behalf of Andrew Grieve agri...@chromium.org Sent: Friday, July 11, 2014 11:39 AM To: dev Subject: Re: Pointing docs to edge Yeah, plugin docs are already gone from docs.cordova.io. This change is strictly for guides platform docs. The main motivation here is that it doesn't make sense to have versioned docs if platform versions diverge anyways. It actually already makes little sense for the tools guides, since they are released more often the platforms. On Fri, Jul 11, 2014 at 12:36 PM, Max Woghiren m...@chromium.org wrote: My understanding is that plugin docs live in plugin repos and will be versioned alongside the plugins themselves. They'll be removed from docs.cordova.io. On Fri, Jul 11, 2014 at 11:49 AM, Ray Camden rayca...@adobe.com wrote: Is edge what people use when they get the latest version of cordova or a plugin? If not, I'd strongly argue against it. If I download the Camera plugin, I expect the default docs to match whats shipped in that version. From: m...@google.com m...@google.com on behalf of Max Woghiren m...@chromium.org Sent: Friday, July 11, 2014 10:46 AM To: dev Subject: Pointing docs to edge Just wanted to bring back this conversation—how does everyone feel about switching docs.cordova.io to point to edge? There has been some discussion about cutting versioned docs after 3.5.0, and we're approaching a good time to do it. :)
Re: Pointing docs to edge
Good point Ray. Another option would be to create a branch-per-component e.g. tools, android, ios, etc. that changes go into, and then merge into master from the branch that corresponds to the release that is happening On Fri, Jul 11, 2014 at 2:02 PM, Michal Mocny mmo...@chromium.org wrote: Ray, but I thought we always wanted more cowbell? Sorry, had to. I agree with Ray here, but I would also want to see latest fixes to docs that apply to released version. Suggestion: rely on discipline to markup documentation changes which only apply to development versions? e.g. div class=available-in-4.0 Now with more ---cowbell! /div And part of release instructions is to change styling from looking scary/experimental to looking ordinary? -Michal On Fri, Jul 11, 2014 at 1:51 PM, Ray Camden rayca...@adobe.com wrote: Ok, so let me rephrase then. Imagine the next version of the CLI adds cowbell support: cordova cowbell --epic but this is NOT in the release version. If I go to docs.cordova.io, click on The Command Line Interface, will I see cowbell documented? If so, I think that is a mistake. From: agri...@google.com agri...@google.com on behalf of Andrew Grieve agri...@chromium.org Sent: Friday, July 11, 2014 11:39 AM To: dev Subject: Re: Pointing docs to edge Yeah, plugin docs are already gone from docs.cordova.io. This change is strictly for guides platform docs. The main motivation here is that it doesn't make sense to have versioned docs if platform versions diverge anyways. It actually already makes little sense for the tools guides, since they are released more often the platforms. On Fri, Jul 11, 2014 at 12:36 PM, Max Woghiren m...@chromium.org wrote: My understanding is that plugin docs live in plugin repos and will be versioned alongside the plugins themselves. They'll be removed from docs.cordova.io. On Fri, Jul 11, 2014 at 11:49 AM, Ray Camden rayca...@adobe.com wrote: Is edge what people use when they get the latest version of cordova or a plugin? If not, I'd strongly argue against it. If I download the Camera plugin, I expect the default docs to match whats shipped in that version. From: m...@google.com m...@google.com on behalf of Max Woghiren m...@chromium.org Sent: Friday, July 11, 2014 10:46 AM To: dev Subject: Pointing docs to edge Just wanted to bring back this conversation—how does everyone feel about switching docs.cordova.io to point to edge? There has been some discussion about cutting versioned docs after 3.5.0, and we're approaching a good time to do it. :)
