Re: Where to keep release notes?
On Sat, Jul 13, 2013 at 3:17 PM, Rob Weir robw...@apache.org wrote: On Fri, Jul 12, 2013 at 7:54 PM, Kay Schenk kay.sch...@gmail.com wrote: On Fri, Jul 12, 2013 at 4:45 PM, Rob Weir robw...@apache.org wrote: On Fri, Jul 12, 2013 at 3:52 PM, Kay Schenk kay.sch...@gmail.com wrote: On Fri, Jul 12, 2013 at 12:17 PM, Rob Weir rabas...@gmail.com wrote: On Jul 12, 2013, at 2:26 PM, Marcus (OOo) marcus.m...@wtnet.de wrote: Am 07/12/2013 07:18 PM, schrieb janI: On 12 July 2013 18:49, Rob Weirrobw...@apache.org wrote: In the past we drafted release notes on the wiki, and then moved them to a location on the website. I'd like to challenge our thinking on this. Wouldn't it be useful to keep the release notes as a live document on the wiki, so we can easily update it with additional information on known issues as they are found, especially after release? I see your point, however I disagree. I think the release doc. for 4.0 is part of the release and should be frozen in svn like all other release artifacts. This is done by having it as a static web page. I support the doubts of Jan. The release notes should be seen as an artifact from a release as they describe this. We can also go that far that we write down the SVN revision number into the release notes. Then they are really tied strictly to this release and nothing else. And I did not mean to suggest anything else. The wiki page would be tied to a specific version of AOO, a different page for each version. But it would be updated to reflect the latest info, especially in the known problems section. We can then have a latest information, which are live in wiki. What about to put a link like this at the top of the release notes to give it more visible attention: Text: For the latest information about Apache OpenOffice 4.0 see this related Wiki page. Link: http://wiki.openoffice.org/wiki/AOO400_Lastest_Info Look at it from the perspective of the user. They want one place to go for relevant info related to the release and problems they might encounter. They don't want to hunt around for old versus new info. Those distinctions are not relevant to a new user. For example, imagine Windows 8.1 comes out and causes a problem with AOO4, but there is a good workaround that could save the user much frustration. But the release notes don't mention this. They just say Windows 8 is tested. This is not very helpful. Then new and important / noteable changes can be documented in the (more easily accessible) Wiki. My proposal was to handle this by keeping the release notes on a wiki page so such changes are seen by users with the least effort for them and us. -Rob Arguments either way it seems. Leaving them on the wiki would certainly be good especially for last minute changes -- which have happened. I guess it boils down to -- when a release is announced, where are the Release Notes of record? and if things change -- i.e. *New* Discovered Issues, as opposed to Known Issues in the Release Notes -- should this be kept as a separate entity that is not part of the Release Notes of record? OK, a lot of legal gobbly gook I guess Two separate considerations, perhaps: 1) Whether Release Notes are updated overtime, post-release, based on feedback from users and discovery of new issues? Or are they frozen-in-time, snapshots that never change, but might point to a different page that is updated. 2) What technology we use to create, publish and (if needed) update the release notes. It is possible to have a living document for Release Notes and do it entirely in HTML on the website. It is possible to do it on the wiki. It is even possible to do it on the committer-only CWiki. (Anyone remember that we have that?) NO -- I do not remember or even know anything about this. I think if we utilized that approach, maybe this is an equitable solution. https://cwiki.apache.org/confluence/display/OOODEV/Wiki+Home This was created when we first started as a podling. But we never really used it. -Rob Let's just go ahead and use that area if you want to move the Release Notes. At some point, we may want to make a copy for the web -- but right now this isn't critical for me as long as the working copy is in a relatively secure area. Time to get our links finalized. I think Confluence may automatically adjust references for those working on this who have the old location bookmarked. Since we all seem to like drafting the release notes on the wiki, it might reduce the work if we just keep it there. It makes it easier for translators as well. But I'm not too concerned with the except technology used. I'm more concerned with
Re: Where to keep release notes?
Kay Schenk wrote: On Sat, Jul 13, 2013 at 3:17 PM, Rob Weir robw...@apache.org wrote: On Fri, Jul 12, 2013 at 7:54 PM, Kay Schenk kay.sch...@gmail.com wrote: On Fri, Jul 12, 2013 at 4:45 PM, Rob Weir robw...@apache.org wrote: On Fri, Jul 12, 2013 at 3:52 PM, Kay Schenk kay.sch...@gmail.com wrote: On Fri, Jul 12, 2013 at 12:17 PM, Rob Weir rabas...@gmail.com wrote: On Jul 12, 2013, at 2:26 PM, Marcus (OOo) marcus.m...@wtnet.de wrote: Am 07/12/2013 07:18 PM, schrieb janI: On 12 July 2013 18:49, Rob Weirrobw...@apache.org wrote: In the past we drafted release notes on the wiki, and then moved them to a location on the website. I'd like to challenge our thinking on this. Wouldn't it be useful to keep the release notes as a live document on the wiki, so we can easily update it with additional information on known issues as they are found, especially after release? I see your point, however I disagree. I think the release doc. for 4.0 is part of the release and should be frozen in svn like all other release artifacts. This is done by having it as a static web page. I support the doubts of Jan. The release notes should be seen as an artifact from a release as they describe this. We can also go that far that we write down the SVN revision number into the release notes. Then they are really tied strictly to this release and nothing else. And I did not mean to suggest anything else. The wiki page would be tied to a specific version of AOO, a different page for each version. But it would be updated to reflect the latest info, especially in the known problems section. We can then have a latest information, which are live in wiki. What about to put a link like this at the top of the release notes to give it more visible attention: Text: For the latest information about Apache OpenOffice 4.0 see this related Wiki page. Link: http://wiki.openoffice.org/wiki/AOO400_Lastest_Info Look at it from the perspective of the user. They want one place to go for relevant info related to the release and problems they might encounter. They don't want to hunt around for old versus new info. Those distinctions are not relevant to a new user. For example, imagine Windows 8.1 comes out and causes a problem with AOO4, but there is a good workaround that could save the user much frustration. But the release notes don't mention this. They just say Windows 8 is tested. This is not very helpful. Then new and important / noteable changes can be documented in the (more easily accessible) Wiki. My proposal was to handle this by keeping the release notes on a wiki page so such changes are seen by users with the least effort for them and us. -Rob Arguments either way it seems. Leaving them on the wiki would certainly be good especially for last minute changes -- which have happened. I guess it boils down to -- when a release is announced, where are the Release Notes of record? and if things change -- i.e. *New* Discovered Issues, as opposed to Known Issues in the Release Notes -- should this be kept as a separate entity that is not part of the Release Notes of record? OK, a lot of legal gobbly gook I guess Two separate considerations, perhaps: 1) Whether Release Notes are updated overtime, post-release, based on feedback from users and discovery of new issues? Or are they frozen-in-time, snapshots that never change, but might point to a different page that is updated. 2) What technology we use to create, publish and (if needed) update the release notes. It is possible to have a living document for Release Notes and do it entirely in HTML on the website. It is possible to do it on the wiki. It is even possible to do it on the committer-only CWiki. (Anyone remember that we have that?) NO -- I do not remember or even know anything about this. I think if we utilized that approach, maybe this is an equitable solution. https://cwiki.apache.org/confluence/display/OOODEV/Wiki+Home This was created when we first started as a podling. But we never really used it. -Rob Let's just go ahead and use that area if you want to move the Release Notes. At some point, we may want to make a copy for the web -- but right now this isn't critical for me as long as the working copy is in a relatively secure area. Time to get our links finalized. I think Confluence may automatically adjust references for those working on this who have the old location bookmarked. The only problem that I see with this is that those of us that are not commiters but have worked extensively on the release notes are effectively shut out. I noticed that th overview of the dev wiki states that you must have a CLA on file. Is that a process that anyone interested can avail themselves of or is it strictly for committers? Regards Keith Since we all seem to like drafting the release notes on the wiki, it might reduce the work if we just keep it there.
Re: Where to keep release notes?
Am 07/13/2013 01:45 AM, schrieb Rob Weir: It is even possible to do it on the committer-only CWiki. (Anyone remember that we have that?) Yes, and we should simply delete this as it is no long used and need. Technically it's of course possible to put the release notes there. But we shouldn't do that on a kind of small road leading to nowhere. OK, I'm wander from the subject. ;-) Marcus - To unsubscribe, e-mail: dev-unsubscr...@openoffice.apache.org For additional commands, e-mail: dev-h...@openoffice.apache.org
Re: Where to keep release notes?
Am 07/13/2013 01:28 AM, schrieb Rob Weir: On Fri, Jul 12, 2013 at 4:44 PM, Marcus (OOo)marcus.m...@wtnet.de wrote: Am 07/12/2013 09:17 PM, schrieb Rob Weir: On Jul 12, 2013, at 2:26 PM, Marcus (OOo)marcus.m...@wtnet.de wrote: Am 07/12/2013 07:18 PM, schrieb janI: On 12 July 2013 18:49, Rob Weirrobw...@apache.orgwrote: In the past we drafted release notes on the wiki, and then moved them to a location on the website. I'd like to challenge our thinking on this. Wouldn't it be useful to keep the release notes as a live document on the wiki, so we can easily update it with additional information on known issues as they are found, especially after release? I see your point, however I disagree. I think the release doc. for 4.0 is part of the release and should be frozen in svn like all other release artifacts. This is done by having it as a static web page. I support the doubts of Jan. The release notes should be seen as an artifact from a release as they describe this. We can also go that far that we write down the SVN revision number into the release notes. Then they are really tied strictly to this release and nothing else. And I did not mean to suggest anything else. The wiki page would be tied to a specific version of AOO, a different page for each version. But it would be updated to reflect the latest info, especially in the known problems section. You suggested to put the release notes *and* latest information into the Wiki, not only the last. Specifically, I'm proposing that these are the same thing. Remember, we already have a section in the release notes called known issues. It sounds like you want that to be a snapshot of what was known at a fixed point in time, and then force the user to go to a different page to find timely information. Why make them do that? Of course not. I wrote that the normal release notes should go to the webpage and the section(s) that can change (e.g., known issues) can go to the Wiki. We can then have a latest information, which are live in wiki. What about to put a link like this at the top of the release notes to give it more visible attention: Text: For the latest information about Apache OpenOffice 4.0 see this related Wiki page. Link: http://wiki.openoffice.org/wiki/AOO400_Lastest_Info Look at it from the perspective of the user. They want one place to go for relevant info related to the release and problems they might encounter. They don't want to hunt around for old versus new info. Those distinctions are not relevant to a new user. Look from the perspective of a forum user. They ask Why does function X not work on OS Y? and they could be pointed to the Wiki page with the Known Issues part, without the need to read all the oher stuff. If the user was not able to find a solution themselves then we have already failed. The forums are not a solution for 50 million users. We still need to make an effort to provide relevant information to the user *at the time they download AOO*. Yes, up to then we have to point them after the download / install to the information. A specific example. AOO 3.4.0 had a problem with migration extensions which caused a crash that lead to a huge number of reports to the forums and the mailing list and bugzilla. We're still cleaning up the mess. We get many reports on this on Facebook as well. Doesn't it make sense for the user to know about this information, and the easy workaround, when they download AOO initially? Why make them hunt for the info? There is no hunt when there is a clear way to find the information. When we put the link on some prominent places then the Google index can help us. The user searches for Known issues, major problems or what ever and can find the Wiki page realtiviley easily. For example, imagine Windows 8.1 comes out and causes a problem with AOO4, but there is a good workaround that could save the user much frustration. But the release notes don't mention this. They just say Windows 8 is tested. This is not very helpful. Great, just point them to the Wiki page. Again, I'm trying to encourage self-service remedies for millions of users. Once they come here to ask a question they are already frustrated and we have already failed them. When we have millions of users with problems we have a totally different problem. ;-) Then new and important / noteable changes can be documented in the (more easily accessible) Wiki. My proposal was to handle this by keeping the release notes on a wiki page so such changes are seen by users with the least effort for them and us. I still would like to see the (real) release notes in SVN control and finally on a webpage. And the things that occur suddenly until the next release can go into the Wiki. We are not that far away from each others opinion. ;-) Perhaps, but I would like you to consider again this from the user's perspective and what would make it easiest for them to
Re: Where to keep release notes?
Am 07/13/2013 01:45 AM, schrieb Rob Weir: On Fri, Jul 12, 2013 at 3:52 PM, Kay Schenkkay.sch...@gmail.com wrote: On Fri, Jul 12, 2013 at 12:17 PM, Rob Weirrabas...@gmail.com wrote: On Jul 12, 2013, at 2:26 PM, Marcus (OOo)marcus.m...@wtnet.de wrote: Am 07/12/2013 07:18 PM, schrieb janI: On 12 July 2013 18:49, Rob Weirrobw...@apache.org wrote: In the past we drafted release notes on the wiki, and then moved them to a location on the website. I'd like to challenge our thinking on this. Wouldn't it be useful to keep the release notes as a live document on the wiki, so we can easily update it with additional information on known issues as they are found, especially after release? I see your point, however I disagree. I think the release doc. for 4.0 is part of the release and should be frozen in svn like all other release artifacts. This is done by having it as a static web page. I support the doubts of Jan. The release notes should be seen as an artifact from a release as they describe this. We can also go that far that we write down the SVN revision number into the release notes. Then they are really tied strictly to this release and nothing else. And I did not mean to suggest anything else. The wiki page would be tied to a specific version of AOO, a different page for each version. But it would be updated to reflect the latest info, especially in the known problems section. We can then have a latest information, which are live in wiki. What about to put a link like this at the top of the release notes to give it more visible attention: Text: For the latest information about Apache OpenOffice 4.0 see this related Wiki page. Link: http://wiki.openoffice.org/wiki/AOO400_Lastest_Info Look at it from the perspective of the user. They want one place to go for relevant info related to the release and problems they might encounter. They don't want to hunt around for old versus new info. Those distinctions are not relevant to a new user. For example, imagine Windows 8.1 comes out and causes a problem with AOO4, but there is a good workaround that could save the user much frustration. But the release notes don't mention this. They just say Windows 8 is tested. This is not very helpful. Then new and important / noteable changes can be documented in the (more easily accessible) Wiki. My proposal was to handle this by keeping the release notes on a wiki page so such changes are seen by users with the least effort for them and us. -Rob Arguments either way it seems. Leaving them on the wiki would certainly be good especially for last minute changes -- which have happened. I guess it boils down to -- when a release is announced, where are the Release Notes of record? and if things change -- i.e. *New* Discovered Issues, as opposed to Known Issues in the Release Notes -- should this be kept as a separate entity that is not part of the Release Notes of record? OK, a lot of legal gobbly gook I guess Two separate considerations, perhaps: 1) Whether Release Notes are updated overtime, post-release, based on feedback from users and discovery of new issues? Or are they frozen-in-time, snapshots that never change, but might point to a different page that is updated. 2) What technology we use to create, publish and (if needed) update the release notes. It is possible to have a living document for Release Notes and do it entirely in HTML on the website. It is possible to do it on the wiki. It is even possible to do it on the committer-only CWiki. (Anyone remember that we have that?) Since we all seem to like drafting the release notes on the wiki, it might reduce the work if we just keep it there. It makes it easier for translators as well. But I'm not too concerned with the except technology used. I'm more concerned with keeping it up to date, and easy to understand. In other words, if we have a section called known issues, I want it to remain accurate as new issues are discovered. It is 2013 and this is the internet. We shouldn't have a let's slip an errata sheet into a hardbound book mentality about this. I personally find it annoying to get instructions and issues at a site one day, that somehow morph into something else the next. Even if these things are not legally binding, there's that sort of confusion factor. I think most users consult the page rarely. They might look once when they install initially. And then they look again perhaps, if they run into a problem. One advantage of the release notes in particular (and this is true of no other page) is that they tend to have higher Google PageRank, because they are linked to from news articles. So users who query for things like apache openoffice 4.0 issues will tend to find that page high on their results list. This would not be true for issues that we push off to another, secondary page. I, too, really don't like the idea of anyone with a wiki account being able to change these,
Re: Where to keep release notes?
On Fri, Jul 12, 2013 at 7:54 PM, Kay Schenk kay.sch...@gmail.com wrote: On Fri, Jul 12, 2013 at 4:45 PM, Rob Weir robw...@apache.org wrote: On Fri, Jul 12, 2013 at 3:52 PM, Kay Schenk kay.sch...@gmail.com wrote: On Fri, Jul 12, 2013 at 12:17 PM, Rob Weir rabas...@gmail.com wrote: On Jul 12, 2013, at 2:26 PM, Marcus (OOo) marcus.m...@wtnet.de wrote: Am 07/12/2013 07:18 PM, schrieb janI: On 12 July 2013 18:49, Rob Weirrobw...@apache.org wrote: In the past we drafted release notes on the wiki, and then moved them to a location on the website. I'd like to challenge our thinking on this. Wouldn't it be useful to keep the release notes as a live document on the wiki, so we can easily update it with additional information on known issues as they are found, especially after release? I see your point, however I disagree. I think the release doc. for 4.0 is part of the release and should be frozen in svn like all other release artifacts. This is done by having it as a static web page. I support the doubts of Jan. The release notes should be seen as an artifact from a release as they describe this. We can also go that far that we write down the SVN revision number into the release notes. Then they are really tied strictly to this release and nothing else. And I did not mean to suggest anything else. The wiki page would be tied to a specific version of AOO, a different page for each version. But it would be updated to reflect the latest info, especially in the known problems section. We can then have a latest information, which are live in wiki. What about to put a link like this at the top of the release notes to give it more visible attention: Text: For the latest information about Apache OpenOffice 4.0 see this related Wiki page. Link: http://wiki.openoffice.org/wiki/AOO400_Lastest_Info Look at it from the perspective of the user. They want one place to go for relevant info related to the release and problems they might encounter. They don't want to hunt around for old versus new info. Those distinctions are not relevant to a new user. For example, imagine Windows 8.1 comes out and causes a problem with AOO4, but there is a good workaround that could save the user much frustration. But the release notes don't mention this. They just say Windows 8 is tested. This is not very helpful. Then new and important / noteable changes can be documented in the (more easily accessible) Wiki. My proposal was to handle this by keeping the release notes on a wiki page so such changes are seen by users with the least effort for them and us. -Rob Arguments either way it seems. Leaving them on the wiki would certainly be good especially for last minute changes -- which have happened. I guess it boils down to -- when a release is announced, where are the Release Notes of record? and if things change -- i.e. *New* Discovered Issues, as opposed to Known Issues in the Release Notes -- should this be kept as a separate entity that is not part of the Release Notes of record? OK, a lot of legal gobbly gook I guess Two separate considerations, perhaps: 1) Whether Release Notes are updated overtime, post-release, based on feedback from users and discovery of new issues? Or are they frozen-in-time, snapshots that never change, but might point to a different page that is updated. 2) What technology we use to create, publish and (if needed) update the release notes. It is possible to have a living document for Release Notes and do it entirely in HTML on the website. It is possible to do it on the wiki. It is even possible to do it on the committer-only CWiki. (Anyone remember that we have that?) NO -- I do not remember or even know anything about this. I think if we utilized that approach, maybe this is an equitable solution. https://cwiki.apache.org/confluence/display/OOODEV/Wiki+Home This was created when we first started as a podling. But we never really used it. -Rob Since we all seem to like drafting the release notes on the wiki, it might reduce the work if we just keep it there. It makes it easier for translators as well. But I'm not too concerned with the except technology used. I'm more concerned with keeping it up to date, and easy to understand. I understand. In other words, if we have a section called known issues, I want it to remain accurate as new issues are discovered. It is 2013 and this is the internet. We shouldn't have a let's slip an errata sheet into a hardbound book mentality about this. Your points are good for this. Really my major concern with the wiki was maybe the ease of unwarranted edits. Other than that, I'm fine with this...dealing with proting it to web server is not that hard but a step we might all be happy to avoid. now to look into the
Where to keep release notes?
In the past we drafted release notes on the wiki, and then moved them to a location on the website. I'd like to challenge our thinking on this. Wouldn't it be useful to keep the release notes as a live document on the wiki, so we can easily update it with additional information on known issues as they are found, especially after release? Remember, even if the issue is not caused by AOO code, a new upgrade to a dependent operating system or other 3rd party application can cause new issues to appear at any time. So keeping the release notes updated is important. Do we lose anything if we do this? For example, is there a concern that the wiki can not handle the load? -Rob - To unsubscribe, e-mail: dev-unsubscr...@openoffice.apache.org For additional commands, e-mail: dev-h...@openoffice.apache.org
Re: Where to keep release notes?
On 12 July 2013 18:49, Rob Weir robw...@apache.org wrote: In the past we drafted release notes on the wiki, and then moved them to a location on the website. I'd like to challenge our thinking on this. Wouldn't it be useful to keep the release notes as a live document on the wiki, so we can easily update it with additional information on known issues as they are found, especially after release? I see your point, however I disagree. I think the release doc. for 4.0 is part of the release and should be frozen in svn like all other release artifacts. This is done by having it as a static web page. We can then have a latest information, which are live in wiki. Remember, even if the issue is not caused by AOO code, a new upgrade to a dependent operating system or other 3rd party application can cause new issues to appear at any time. So keeping the release notes updated is important. This issue is highly caused by AOO code, remember the release code is tested with a given set of third party libraries and given versions of the operating systems. Release notes reflect the environment tested for the 4.0 release, everything that comes later should either be kept in a separate document or postponed to a new release. Do we lose anything if we do this? For example, is there a concern that the wiki can not handle the load? Wiki can handle the load (it must because a lot of people will search for info). Yes we loose trackability. Release notes is in svn (in my opinion). Remember in wiki anybody can change, so if person X test AOO on platform Y should he/she then just update the release documentation, I hope not. But again, your idea of a live document is good, I just see it as a second document (similar to what a lot of companies does). rgds jan I. -Rob - To unsubscribe, e-mail: dev-unsubscr...@openoffice.apache.org For additional commands, e-mail: dev-h...@openoffice.apache.org
Re: Where to keep release notes?
On Jul 12, 2013, at 1:18 PM, janI j...@apache.org wrote: On 12 July 2013 18:49, Rob Weir robw...@apache.org wrote: In the past we drafted release notes on the wiki, and then moved them to a location on the website. I'd like to challenge our thinking on this. Wouldn't it be useful to keep the release notes as a live document on the wiki, so we can easily update it with additional information on known issues as they are found, especially after release? I see your point, however I disagree. I think the release doc. for 4.0 is part of the release and should be frozen in svn like all other release artifacts. This is done by having it as a static web page. It may be in SVN but it is not part of the release in any formal sense. We can then have a latest information, which are live in wiki. That could work, especially if we gave a prominent link from the Release Notes to the latest info wiki page. -Rob Remember, even if the issue is not caused by AOO code, a new upgrade to a dependent operating system or other 3rd party application can cause new issues to appear at any time. So keeping the release notes updated is important. This issue is highly caused by AOO code, remember the release code is tested with a given set of third party libraries and given versions of the operating systems. Release notes reflect the environment tested for the 4.0 release, everything that comes later should either be kept in a separate document or postponed to a new release. That is logical, but I'm not sure the user (the target audience for the Release Notes) would see it the same way. They only care about accurate info related to their platform and configuration. The less searching they can do to find this info, the better. Do we lose anything if we do this? For example, is there a concern that the wiki can not handle the load? Wiki can handle the load (it must because a lot of people will search for info). Yes we loose trackability. Release notes is in svn (in my opinion). Remember in wiki anybody can change, so if person X test AOO on platform Y should he/she then just update the release documentation, I hope not. But again, your idea of a live document is good, I just see it as a second document (similar to what a lot of companies does). rgds jan I. -Rob - To unsubscribe, e-mail: dev-unsubscr...@openoffice.apache.org For additional commands, e-mail: dev-h...@openoffice.apache.org - To unsubscribe, e-mail: dev-unsubscr...@openoffice.apache.org For additional commands, e-mail: dev-h...@openoffice.apache.org
Re: Where to keep release notes?
Am 07/12/2013 07:18 PM, schrieb janI: On 12 July 2013 18:49, Rob Weirrobw...@apache.org wrote: In the past we drafted release notes on the wiki, and then moved them to a location on the website. I'd like to challenge our thinking on this. Wouldn't it be useful to keep the release notes as a live document on the wiki, so we can easily update it with additional information on known issues as they are found, especially after release? I see your point, however I disagree. I think the release doc. for 4.0 is part of the release and should be frozen in svn like all other release artifacts. This is done by having it as a static web page. I support the doubts of Jan. The release notes should be seen as an artifact from a release as they describe this. We can also go that far that we write down the SVN revision number into the release notes. Then they are really tied strictly to this release and nothing else. We can then have a latest information, which are live in wiki. What about to put a link like this at the top of the release notes to give it more visible attention: Text: For the latest information about Apache OpenOffice 4.0 see this related Wiki page. Link: http://wiki.openoffice.org/wiki/AOO400_Lastest_Info Then new and important / noteable changes can be documented in the (more easily accessible) Wiki. My 2 ct. Marcus Remember, even if the issue is not caused by AOO code, a new upgrade to a dependent operating system or other 3rd party application can cause new issues to appear at any time. So keeping the release notes updated is important. This issue is highly caused by AOO code, remember the release code is tested with a given set of third party libraries and given versions of the operating systems. Release notes reflect the environment tested for the 4.0 release, everything that comes later should either be kept in a separate document or postponed to a new release. Do we lose anything if we do this? For example, is there a concern that the wiki can not handle the load? Wiki can handle the load (it must because a lot of people will search for info). Yes we loose trackability. Release notes is in svn (in my opinion). Remember in wiki anybody can change, so if person X test AOO on platform Y should he/she then just update the release documentation, I hope not. But again, your idea of a live document is good, I just see it as a second document (similar to what a lot of companies does). - To unsubscribe, e-mail: dev-unsubscr...@openoffice.apache.org For additional commands, e-mail: dev-h...@openoffice.apache.org
Re: Where to keep release notes?
On Jul 12, 2013, at 2:26 PM, Marcus (OOo) marcus.m...@wtnet.de wrote: Am 07/12/2013 07:18 PM, schrieb janI: On 12 July 2013 18:49, Rob Weirrobw...@apache.org wrote: In the past we drafted release notes on the wiki, and then moved them to a location on the website. I'd like to challenge our thinking on this. Wouldn't it be useful to keep the release notes as a live document on the wiki, so we can easily update it with additional information on known issues as they are found, especially after release? I see your point, however I disagree. I think the release doc. for 4.0 is part of the release and should be frozen in svn like all other release artifacts. This is done by having it as a static web page. I support the doubts of Jan. The release notes should be seen as an artifact from a release as they describe this. We can also go that far that we write down the SVN revision number into the release notes. Then they are really tied strictly to this release and nothing else. And I did not mean to suggest anything else. The wiki page would be tied to a specific version of AOO, a different page for each version. But it would be updated to reflect the latest info, especially in the known problems section. We can then have a latest information, which are live in wiki. What about to put a link like this at the top of the release notes to give it more visible attention: Text: For the latest information about Apache OpenOffice 4.0 see this related Wiki page. Link: http://wiki.openoffice.org/wiki/AOO400_Lastest_Info Look at it from the perspective of the user. They want one place to go for relevant info related to the release and problems they might encounter. They don't want to hunt around for old versus new info. Those distinctions are not relevant to a new user. For example, imagine Windows 8.1 comes out and causes a problem with AOO4, but there is a good workaround that could save the user much frustration. But the release notes don't mention this. They just say Windows 8 is tested. This is not very helpful. Then new and important / noteable changes can be documented in the (more easily accessible) Wiki. My proposal was to handle this by keeping the release notes on a wiki page so such changes are seen by users with the least effort for them and us. -Rob My 2 ct. Marcus Remember, even if the issue is not caused by AOO code, a new upgrade to a dependent operating system or other 3rd party application can cause new issues to appear at any time. So keeping the release notes updated is important. This issue is highly caused by AOO code, remember the release code is tested with a given set of third party libraries and given versions of the operating systems. Release notes reflect the environment tested for the 4.0 release, everything that comes later should either be kept in a separate document or postponed to a new release. Do we lose anything if we do this? For example, is there a concern that the wiki can not handle the load? Wiki can handle the load (it must because a lot of people will search for info). Yes we loose trackability. Release notes is in svn (in my opinion). Remember in wiki anybody can change, so if person X test AOO on platform Y should he/she then just update the release documentation, I hope not. But again, your idea of a live document is good, I just see it as a second document (similar to what a lot of companies does). - To unsubscribe, e-mail: dev-unsubscr...@openoffice.apache.org For additional commands, e-mail: dev-h...@openoffice.apache.org - To unsubscribe, e-mail: dev-unsubscr...@openoffice.apache.org For additional commands, e-mail: dev-h...@openoffice.apache.org
Re: Where to keep release notes?
On 12 July 2013 22:44, Marcus (OOo) marcus.m...@wtnet.de wrote: Am 07/12/2013 09:17 PM, schrieb Rob Weir: On Jul 12, 2013, at 2:26 PM, Marcus (OOo)marcus.m...@wtnet.de wrote: Am 07/12/2013 07:18 PM, schrieb janI: On 12 July 2013 18:49, Rob Weirrobw...@apache.org wrote: In the past we drafted release notes on the wiki, and then moved them to a location on the website. I'd like to challenge our thinking on this. Wouldn't it be useful to keep the release notes as a live document on the wiki, so we can easily update it with additional information on known issues as they are found, especially after release? I see your point, however I disagree. I think the release doc. for 4.0 is part of the release and should be frozen in svn like all other release artifacts. This is done by having it as a static web page. I support the doubts of Jan. The release notes should be seen as an artifact from a release as they describe this. We can also go that far that we write down the SVN revision number into the release notes. Then they are really tied strictly to this release and nothing else. And I did not mean to suggest anything else. The wiki page would be tied to a specific version of AOO, a different page for each version. But it would be updated to reflect the latest info, especially in the known problems section. You suggested to put the release notes *and* latest information into the Wiki, not only the last. We can then have a latest information, which are live in wiki. What about to put a link like this at the top of the release notes to give it more visible attention: Text: For the latest information about Apache OpenOffice 4.0 see this related Wiki page. Link: http://wiki.openoffice.org/**wiki/AOO400_Lastest_Infohttp://wiki.openoffice.org/wiki/AOO400_Lastest_Info Look at it from the perspective of the user. They want one place to go for relevant info related to the release and problems they might encounter. They don't want to hunt around for old versus new info. Those distinctions are not relevant to a new user. Look from the perspective of a forum user. They ask Why does function X not work on OS Y? and they could be pointed to the Wiki page with the Known Issues part, without the need to read all the oher stuff. For example, imagine Windows 8.1 comes out and causes a problem with AOO4, but there is a good workaround that could save the user much frustration. But the release notes don't mention this. They just say Windows 8 is tested. This is not very helpful. Great, just point them to the Wiki page. Then new and important / noteable changes can be documented in the (more easily accessible) Wiki. My proposal was to handle this by keeping the release notes on a wiki page so such changes are seen by users with the least effort for them and us. I still would like to see the (real) release notes in SVN control and finally on a webpage. And the things that occur suddenly until the next release can go into the Wiki. We are not that far away from each others opinion. ;-) I think you have an extra point, compared to my first post. Keeping (real) release notes fixed (web page / svn) and have last notes in wiki, will make the latter slim and fast to read, so we can hope the users actually read it. rgds jan I. Marcus Remember, even if the issue is not caused by AOO code, a new upgrade to a dependent operating system or other 3rd party application can cause new issues to appear at any time. So keeping the release notes updated is important. This issue is highly caused by AOO code, remember the release code is tested with a given set of third party libraries and given versions of the operating systems. Release notes reflect the environment tested for the 4.0 release, everything that comes later should either be kept in a separate document or postponed to a new release. Do we lose anything if we do this? For example, is there a concern that the wiki can not handle the load? Wiki can handle the load (it must because a lot of people will search for info). Yes we loose trackability. Release notes is in svn (in my opinion). Remember in wiki anybody can change, so if person X test AOO on platform Y should he/she then just update the release documentation, I hope not. But again, your idea of a live document is good, I just see it as a second document (similar to what a lot of companies does). --**--**- To unsubscribe, e-mail: dev-unsubscribe@openoffice.**apache.orgdev-unsubscr...@openoffice.apache.org For additional commands, e-mail: dev-h...@openoffice.apache.org
Re: Where to keep release notes?
On Fri, Jul 12, 2013 at 4:44 PM, Marcus (OOo) marcus.m...@wtnet.de wrote: Am 07/12/2013 09:17 PM, schrieb Rob Weir: On Jul 12, 2013, at 2:26 PM, Marcus (OOo)marcus.m...@wtnet.de wrote: Am 07/12/2013 07:18 PM, schrieb janI: On 12 July 2013 18:49, Rob Weirrobw...@apache.org wrote: In the past we drafted release notes on the wiki, and then moved them to a location on the website. I'd like to challenge our thinking on this. Wouldn't it be useful to keep the release notes as a live document on the wiki, so we can easily update it with additional information on known issues as they are found, especially after release? I see your point, however I disagree. I think the release doc. for 4.0 is part of the release and should be frozen in svn like all other release artifacts. This is done by having it as a static web page. I support the doubts of Jan. The release notes should be seen as an artifact from a release as they describe this. We can also go that far that we write down the SVN revision number into the release notes. Then they are really tied strictly to this release and nothing else. And I did not mean to suggest anything else. The wiki page would be tied to a specific version of AOO, a different page for each version. But it would be updated to reflect the latest info, especially in the known problems section. You suggested to put the release notes *and* latest information into the Wiki, not only the last. Specifically, I'm proposing that these are the same thing. Remember, we already have a section in the release notes called known issues. It sounds like you want that to be a snapshot of what was known at a fixed point in time, and then force the user to go to a different page to find timely information. Why make them do that? We can then have a latest information, which are live in wiki. What about to put a link like this at the top of the release notes to give it more visible attention: Text: For the latest information about Apache OpenOffice 4.0 see this related Wiki page. Link: http://wiki.openoffice.org/wiki/AOO400_Lastest_Info Look at it from the perspective of the user. They want one place to go for relevant info related to the release and problems they might encounter. They don't want to hunt around for old versus new info. Those distinctions are not relevant to a new user. Look from the perspective of a forum user. They ask Why does function X not work on OS Y? and they could be pointed to the Wiki page with the Known Issues part, without the need to read all the oher stuff. If the user was not able to find a solution themselves then we have already failed. The forums are not a solution for 50 million users. We still need to make an effort to provide relevant information to the user *at the time they download AOO*. A specific example. AOO 3.4.0 had a problem with migration extensions which caused a crash that lead to a huge number of reports to the forums and the mailing list and bugzilla. We're still cleaning up the mess. We get many reports on this on Facebook as well. Doesn't it make sense for the user to know about this information, and the easy workaround, when they download AOO initially? Why make them hunt for the info? Is it really relevant, from a user support perspective, whether the issue and workaround was known on the day we released versus an issue found a month later? Do you really think the user expects the former to be found in one place and the latter in another place? Really? For example, imagine Windows 8.1 comes out and causes a problem with AOO4, but there is a good workaround that could save the user much frustration. But the release notes don't mention this. They just say Windows 8 is tested. This is not very helpful. Great, just point them to the Wiki page. Again, I'm trying to encourage self-service remedies for millions of users. Once they come here to ask a question they are already frustrated and we have already failed them. Then new and important / noteable changes can be documented in the (more easily accessible) Wiki. My proposal was to handle this by keeping the release notes on a wiki page so such changes are seen by users with the least effort for them and us. I still would like to see the (real) release notes in SVN control and finally on a webpage. And the things that occur suddenly until the next release can go into the Wiki. We are not that far away from each others opinion. ;-) Perhaps, but I would like you to consider again this from the user's perspective and what would make it easiest for them to resolve issues without flooding our mailing lists for questions that we already know about. Regards, -Rob Marcus Remember, even if the issue is not caused by AOO code, a new upgrade to a dependent operating system or other 3rd party application can cause new issues to appear at any time. So keeping the release notes updated is
Re: Where to keep release notes?
On Fri, Jul 12, 2013 at 5:39 PM, janI j...@apache.org wrote: On 12 July 2013 22:44, Marcus (OOo) marcus.m...@wtnet.de wrote: Am 07/12/2013 09:17 PM, schrieb Rob Weir: On Jul 12, 2013, at 2:26 PM, Marcus (OOo)marcus.m...@wtnet.de wrote: Am 07/12/2013 07:18 PM, schrieb janI: On 12 July 2013 18:49, Rob Weirrobw...@apache.org wrote: In the past we drafted release notes on the wiki, and then moved them to a location on the website. I'd like to challenge our thinking on this. Wouldn't it be useful to keep the release notes as a live document on the wiki, so we can easily update it with additional information on known issues as they are found, especially after release? I see your point, however I disagree. I think the release doc. for 4.0 is part of the release and should be frozen in svn like all other release artifacts. This is done by having it as a static web page. I support the doubts of Jan. The release notes should be seen as an artifact from a release as they describe this. We can also go that far that we write down the SVN revision number into the release notes. Then they are really tied strictly to this release and nothing else. And I did not mean to suggest anything else. The wiki page would be tied to a specific version of AOO, a different page for each version. But it would be updated to reflect the latest info, especially in the known problems section. You suggested to put the release notes *and* latest information into the Wiki, not only the last. We can then have a latest information, which are live in wiki. What about to put a link like this at the top of the release notes to give it more visible attention: Text: For the latest information about Apache OpenOffice 4.0 see this related Wiki page. Link: http://wiki.openoffice.org/**wiki/AOO400_Lastest_Infohttp://wiki.openoffice.org/wiki/AOO400_Lastest_Info Look at it from the perspective of the user. They want one place to go for relevant info related to the release and problems they might encounter. They don't want to hunt around for old versus new info. Those distinctions are not relevant to a new user. Look from the perspective of a forum user. They ask Why does function X not work on OS Y? and they could be pointed to the Wiki page with the Known Issues part, without the need to read all the oher stuff. For example, imagine Windows 8.1 comes out and causes a problem with AOO4, but there is a good workaround that could save the user much frustration. But the release notes don't mention this. They just say Windows 8 is tested. This is not very helpful. Great, just point them to the Wiki page. Then new and important / noteable changes can be documented in the (more easily accessible) Wiki. My proposal was to handle this by keeping the release notes on a wiki page so such changes are seen by users with the least effort for them and us. I still would like to see the (real) release notes in SVN control and finally on a webpage. And the things that occur suddenly until the next release can go into the Wiki. We are not that far away from each others opinion. ;-) I think you have an extra point, compared to my first post. Keeping (real) release notes fixed (web page / svn) and have last notes in wiki, will make the latter slim and fast to read, so we can hope the users actually read it. Imagine you take some medicine, and the jar has some instructions and warnings on it. And then there is some fine print that says, for updated warnings, go to this web page. Do you think that would work well? Perhaps, with physical things we are limited in that way. But if the information is natively digital, why wouldn't you update it in place, so the reader gets all of the information at once? Why would any user care about original versus updated information? Why is that even a distinction that they care about? Don't they really just want to know *only* the relevant current information? As for keeping it slim, I agree there. But that does not mean that we segregate relevant updated information. It means that we structure the release notes carefully so all information is easy to find, and we make it clear what information is critical. We fail to do that if we put important information on a secondary page just because it was found later. Remember, your approach has already been shown to fail in the case of the profile corruption issue we had with AOO 3.4.0. Why not try sometime else this time? -Rob rgds jan I. Marcus Remember, even if the issue is not caused by AOO code, a new upgrade to a dependent operating system or other 3rd party application can cause new issues to appear at any time. So keeping the release notes updated is important. This issue is highly caused by AOO code, remember the release code is tested with a given set of third party libraries and given versions of the operating systems. Release notes
Re: Where to keep release notes?
On Fri, Jul 12, 2013 at 3:52 PM, Kay Schenk kay.sch...@gmail.com wrote: On Fri, Jul 12, 2013 at 12:17 PM, Rob Weir rabas...@gmail.com wrote: On Jul 12, 2013, at 2:26 PM, Marcus (OOo) marcus.m...@wtnet.de wrote: Am 07/12/2013 07:18 PM, schrieb janI: On 12 July 2013 18:49, Rob Weirrobw...@apache.org wrote: In the past we drafted release notes on the wiki, and then moved them to a location on the website. I'd like to challenge our thinking on this. Wouldn't it be useful to keep the release notes as a live document on the wiki, so we can easily update it with additional information on known issues as they are found, especially after release? I see your point, however I disagree. I think the release doc. for 4.0 is part of the release and should be frozen in svn like all other release artifacts. This is done by having it as a static web page. I support the doubts of Jan. The release notes should be seen as an artifact from a release as they describe this. We can also go that far that we write down the SVN revision number into the release notes. Then they are really tied strictly to this release and nothing else. And I did not mean to suggest anything else. The wiki page would be tied to a specific version of AOO, a different page for each version. But it would be updated to reflect the latest info, especially in the known problems section. We can then have a latest information, which are live in wiki. What about to put a link like this at the top of the release notes to give it more visible attention: Text: For the latest information about Apache OpenOffice 4.0 see this related Wiki page. Link: http://wiki.openoffice.org/wiki/AOO400_Lastest_Info Look at it from the perspective of the user. They want one place to go for relevant info related to the release and problems they might encounter. They don't want to hunt around for old versus new info. Those distinctions are not relevant to a new user. For example, imagine Windows 8.1 comes out and causes a problem with AOO4, but there is a good workaround that could save the user much frustration. But the release notes don't mention this. They just say Windows 8 is tested. This is not very helpful. Then new and important / noteable changes can be documented in the (more easily accessible) Wiki. My proposal was to handle this by keeping the release notes on a wiki page so such changes are seen by users with the least effort for them and us. -Rob Arguments either way it seems. Leaving them on the wiki would certainly be good especially for last minute changes -- which have happened. I guess it boils down to -- when a release is announced, where are the Release Notes of record? and if things change -- i.e. *New* Discovered Issues, as opposed to Known Issues in the Release Notes -- should this be kept as a separate entity that is not part of the Release Notes of record? OK, a lot of legal gobbly gook I guess Two separate considerations, perhaps: 1) Whether Release Notes are updated overtime, post-release, based on feedback from users and discovery of new issues? Or are they frozen-in-time, snapshots that never change, but might point to a different page that is updated. 2) What technology we use to create, publish and (if needed) update the release notes. It is possible to have a living document for Release Notes and do it entirely in HTML on the website. It is possible to do it on the wiki. It is even possible to do it on the committer-only CWiki. (Anyone remember that we have that?) Since we all seem to like drafting the release notes on the wiki, it might reduce the work if we just keep it there. It makes it easier for translators as well. But I'm not too concerned with the except technology used. I'm more concerned with keeping it up to date, and easy to understand. In other words, if we have a section called known issues, I want it to remain accurate as new issues are discovered. It is 2013 and this is the internet. We shouldn't have a let's slip an errata sheet into a hardbound book mentality about this. I personally find it annoying to get instructions and issues at a site one day, that somehow morph into something else the next. Even if these things are not legally binding, there's that sort of confusion factor. I think most users consult the page rarely. They might look once when they install initially. And then they look again perhaps, if they run into a problem. One advantage of the release notes in particular (and this is true of no other page) is that they tend to have higher Google PageRank, because they are linked to from news articles. So users who query for things like apache openoffice 4.0 issues will tend to find that page high on their results list. This would not be true for issues that we push off to another, secondary page. I, too, really don't like the idea of anyone with a wiki account being able to
