You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@openoffice.apache.org by Rob Weir <ro...@apache.org> on 2013/07/12 18:49:39 UTC
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-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
Re: Where to keep release notes?
Posted by "Marcus (OOo)" <ma...@wtnet.de>.
Am 07/13/2013 01:28 AM, schrieb Rob Weir:
> On Fri, Jul 12, 2013 at 4:44 PM, Marcus (OOo)<ma...@wtnet.de> wrote:
>> Am 07/12/2013 09:17 PM, schrieb Rob Weir:
>>
>>> On Jul 12, 2013, at 2:26 PM, "Marcus (OOo)"<ma...@wtnet.de> wrote:
>>>
>>>> Am 07/12/2013 07:18 PM, schrieb janI:
>>>>>
>>>>> On 12 July 2013 18:49, Rob Weir<ro...@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?
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 resolve issues
> without flooding our mailing lists for questions that we already know
> about.
I still think that a "splitted" way would be the best.
A)
The user downloads AOO and is reading the release notes (BTW, how does
he knows that these exist?), clicks on the link and can see all known
issues up to the last edit.
B)
The user has already a problem with AOO and can be pointed (forum, user
list, Google search, ...) to the known issues list, without the need to
read all the othert stuff of the release notes that he is not
interesting in.
That's the way I see the flow.
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.org
For additional commands, e-mail: dev-help@openoffice.apache.org
Re: Where to keep release notes?
Posted by Rob Weir <ro...@apache.org>.
On Fri, Jul 12, 2013 at 4:44 PM, Marcus (OOo) <ma...@wtnet.de> wrote:
> Am 07/12/2013 09:17 PM, schrieb Rob Weir:
>
>> On Jul 12, 2013, at 2:26 PM, "Marcus (OOo)"<ma...@wtnet.de> wrote:
>>
>>> Am 07/12/2013 07:18 PM, schrieb janI:
>>>>
>>>> On 12 July 2013 18:49, Rob Weir<ro...@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 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.org
> For additional commands, e-mail: dev-help@openoffice.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
Re: Where to keep release notes?
Posted by Rob Weir <ro...@apache.org>.
On Fri, Jul 12, 2013 at 5:39 PM, janI <ja...@apache.org> wrote:
> On 12 July 2013 22:44, Marcus (OOo) <ma...@wtnet.de> wrote:
>
>> Am 07/12/2013 09:17 PM, schrieb Rob Weir:
>>
>> On Jul 12, 2013, at 2:26 PM, "Marcus (OOo)"<ma...@wtnet.de> wrote:
>>>
>>> Am 07/12/2013 07:18 PM, schrieb janI:
>>>>
>>>>> On 12 July 2013 18:49, Rob Weir<ro...@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_Info<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.
>>
>>
>> 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 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.org<de...@openoffice.apache.org>
>> For additional commands, e-mail: dev-help@openoffice.apache.org
>>
>>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
Re: Where to keep release notes?
Posted by janI <ja...@apache.org>.
On 12 July 2013 22:44, Marcus (OOo) <ma...@wtnet.de> wrote:
> Am 07/12/2013 09:17 PM, schrieb Rob Weir:
>
> On Jul 12, 2013, at 2:26 PM, "Marcus (OOo)"<ma...@wtnet.de> wrote:
>>
>> Am 07/12/2013 07:18 PM, schrieb janI:
>>>
>>>> On 12 July 2013 18:49, Rob Weir<ro...@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_Info<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.
>
>
> 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.org<de...@openoffice.apache.org>
> For additional commands, e-mail: dev-help@openoffice.apache.org
>
>
Re: Where to keep release notes?
Posted by "Marcus (OOo)" <ma...@wtnet.de>.
Am 07/12/2013 09:17 PM, schrieb Rob Weir:
> On Jul 12, 2013, at 2:26 PM, "Marcus (OOo)"<ma...@wtnet.de> wrote:
>
>> Am 07/12/2013 07:18 PM, schrieb janI:
>>> On 12 July 2013 18:49, Rob Weir<ro...@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_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. ;-)
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.org
For additional commands, e-mail: dev-help@openoffice.apache.org
Re: Where to keep release notes?
Posted by Kay Schenk <ka...@gmail.com>.
On Sun, Jul 14, 2013 at 10:49 AM, Keith N. McKenna <
keith.mckenna@comcast.net> wrote:
> Kay Schenk wrote:
>
>> On Sat, Jul 13, 2013 at 3:17 PM, Rob Weir <ro...@apache.org> wrote:
>>
>> On Fri, Jul 12, 2013 at 7:54 PM, Kay Schenk <ka...@gmail.com>
>>> wrote:
>>>
>>>> On Fri, Jul 12, 2013 at 4:45 PM, Rob Weir <ro...@apache.org> wrote:
>>>>
>>>> On Fri, Jul 12, 2013 at 3:52 PM, Kay Schenk <ka...@gmail.com>
>>>>>
>>>> wrote:
>>>
>>>> On Fri, Jul 12, 2013 at 12:17 PM, Rob Weir <ra...@gmail.com>
>>>>>>
>>>>> wrote:
>>>
>>>>
>>>>>> On Jul 12, 2013, at 2:26 PM, "Marcus (OOo)" <ma...@wtnet.de>
>>>>>>>
>>>>>> wrote:
>>>>>
>>>>>>
>>>>>>> Am 07/12/2013 07:18 PM, schrieb janI:
>>>>>>>>
>>>>>>>>> On 12 July 2013 18:49, Rob Weir<ro...@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<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<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
Hi Keith --
Moving the Release Notes to the committer only DEV area would not be done
until right before release. This is the same end result of moving them to
the web site (as has been done in the past), as only committers can update
the site.
I'm sorry I stated my former comment the way I did. I didn't intend for
them to moved instantly. The Release Notes will likely remain where they
are until the actual release.
In any case, if you ARE interested in becoming a committer, you should
certainly file an ICLA.
>
>
>>>> 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 Committer only wiki (???)
>>>>
>>>>
>>>>
>>>>
>>>>> 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.
>>>>>
>>>>
>>>>
>>>> yes...I agree. Sadly, I see the Install instructions are hardly used at
>>>> all, but I think "for the record", we need to have them.
>>>>
>>>>
>>>>
>>>> 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.
>>>>>
>>>>>
>>>> OK...
>>>>
>>>>
>>>>
>>>>> I, too, really don't like the idea of anyone with a wiki account being
>>>>>>
>>>>> able
>>>>>
>>>>>> to change these, especially with the possibility of no general
>>>>>> consultation or consensus.
>>>>>>
>>>>>>
>>>>> There are ways of handling this that control the ACL, such as using
>>>>> the OOODEV CWiki, or even using static HTML or MDText pages, if the
>>>>> open access of the wiki is a concern.
>>>>>
>>>>>
>>>> I know about the OOODEV CWiki, -- I just never tried to access it.
>>>>
>>>> I'm OK with using that area for the Release Notes.
>>>>
>>>>
>>>>
>>>> Regards,
>>>>>
>>>>> -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-unsubscribe@openoffice.**apache.org<de...@openoffice.apache.org>
>>>>>>>> For additional commands, e-mail: dev-help@openoffice.apache.org
>>>>>>>>
>>>>>>>>
>>>>>>> ------------------------------**------------------------------**
>>>>>>> ---------
>>>>>>> To unsubscribe, e-mail: dev-unsubscribe@openoffice.**apache.org<de...@openoffice.apache.org>
>>>>>>> For additional commands, e-mail: dev-help@openoffice.apache.org
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>
>>>>>> --
>>>>>>
>>>>>>
>>>>> ------------------------------**------------------------------**
>>> ------------------------------**-------
>>>
>>>> MzK
>>>>>>
>>>>>> "Every day we should hear at least one little song,
>>>>>> read one good poem, see one exquisite picture,
>>>>>> and, if possible, speak a few sensible words."
>>>>>> -- Johann Wolfgang von Goethe
>>>>>>
>>>>>
>>>>> ------------------------------**------------------------------**
>>>>> ---------
>>>>> To unsubscribe, e-mail: dev-unsubscribe@openoffice.**apache.org<de...@openoffice.apache.org>
>>>>> For additional commands, e-mail: dev-help@openoffice.apache.org
>>>>>
>>>>>
>>>>>
>>>>
>>>> --
>>>>
>>>> ------------------------------**------------------------------**
>>> ------------------------------**-------
>>>
>>>> MzK
>>>>
>>>> "Every day we should hear at least one little song,
>>>> read one good poem, see one exquisite picture,
>>>> and, if possible, speak a few sensible words."
>>>> -- Johann Wolfgang von Goethe
>>>>
>>>
>>> ------------------------------**------------------------------**
>>> ---------
>>> To unsubscribe, e-mail: dev-unsubscribe@openoffice.**apache.org<de...@openoffice.apache.org>
>>> For additional commands, e-mail: dev-help@openoffice.apache.org
>>>
>>>
>>>
>>
>>
>
>
> ------------------------------**------------------------------**---------
> To unsubscribe, e-mail: dev-unsubscribe@openoffice.**apache.org<de...@openoffice.apache.org>
> For additional commands, e-mail: dev-help@openoffice.apache.org
>
>
--
-------------------------------------------------------------------------------------------------
MzK
Success is falling nine times and getting up ten."
-- Jon Bon Jovi
Re: Where to keep release notes?
Posted by "Keith N. McKenna" <ke...@comcast.net>.
Kay Schenk wrote:
> On Sat, Jul 13, 2013 at 3:17 PM, Rob Weir <ro...@apache.org> wrote:
>
>> On Fri, Jul 12, 2013 at 7:54 PM, Kay Schenk <ka...@gmail.com> wrote:
>>> On Fri, Jul 12, 2013 at 4:45 PM, Rob Weir <ro...@apache.org> wrote:
>>>
>>>> On Fri, Jul 12, 2013 at 3:52 PM, Kay Schenk <ka...@gmail.com>
>> wrote:
>>>>> On Fri, Jul 12, 2013 at 12:17 PM, Rob Weir <ra...@gmail.com>
>> wrote:
>>>>>
>>>>>> On Jul 12, 2013, at 2:26 PM, "Marcus (OOo)" <ma...@wtnet.de>
>>>> wrote:
>>>>>>
>>>>>>> Am 07/12/2013 07:18 PM, schrieb janI:
>>>>>>>> On 12 July 2013 18:49, Rob Weir<ro...@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. 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 Committer only wiki (???)
>>>
>>>
>>>
>>>>
>>>>> 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.
>>>
>>>
>>> yes...I agree. Sadly, I see the Install instructions are hardly used at
>>> all, but I think "for the record", we need to have them.
>>>
>>>
>>>
>>>> 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.
>>>>
>>>
>>> OK...
>>>
>>>
>>>>
>>>>> I, too, really don't like the idea of anyone with a wiki account being
>>>> able
>>>>> to change these, especially with the possibility of no general
>>>>> consultation or consensus.
>>>>>
>>>>
>>>> There are ways of handling this that control the ACL, such as using
>>>> the OOODEV CWiki, or even using static HTML or MDText pages, if the
>>>> open access of the wiki is a concern.
>>>>
>>>
>>> I know about the OOODEV CWiki, -- I just never tried to access it.
>>>
>>> I'm OK with using that area for the Release Notes.
>>>
>>>
>>>
>>>> Regards,
>>>>
>>>> -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-unsubscribe@openoffice.apache.org
>>>>>>> For additional commands, e-mail: dev-help@openoffice.apache.org
>>>>>>>
>>>>>>
>>>>>> ---------------------------------------------------------------------
>>>>>> To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
>>>>>> For additional commands, e-mail: dev-help@openoffice.apache.org
>>>>>>
>>>>>>
>>>>>
>>>>>
>>>>> --
>>>>>
>>>>
>> -------------------------------------------------------------------------------------------------
>>>>> MzK
>>>>>
>>>>> "Every day we should hear at least one little song,
>>>>> read one good poem, see one exquisite picture,
>>>>> and, if possible, speak a few sensible words."
>>>>> -- Johann Wolfgang von Goethe
>>>>
>>>> ---------------------------------------------------------------------
>>>> To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
>>>> For additional commands, e-mail: dev-help@openoffice.apache.org
>>>>
>>>>
>>>
>>>
>>> --
>>>
>> -------------------------------------------------------------------------------------------------
>>> MzK
>>>
>>> "Every day we should hear at least one little song,
>>> read one good poem, see one exquisite picture,
>>> and, if possible, speak a few sensible words."
>>> -- Johann Wolfgang von Goethe
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
>> For additional commands, e-mail: dev-help@openoffice.apache.org
>>
>>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
Re: Where to keep release notes?
Posted by Kay Schenk <ka...@gmail.com>.
On Sat, Jul 13, 2013 at 3:17 PM, Rob Weir <ro...@apache.org> wrote:
> On Fri, Jul 12, 2013 at 7:54 PM, Kay Schenk <ka...@gmail.com> wrote:
> > On Fri, Jul 12, 2013 at 4:45 PM, Rob Weir <ro...@apache.org> wrote:
> >
> >> On Fri, Jul 12, 2013 at 3:52 PM, Kay Schenk <ka...@gmail.com>
> wrote:
> >> > On Fri, Jul 12, 2013 at 12:17 PM, Rob Weir <ra...@gmail.com>
> wrote:
> >> >
> >> >> On Jul 12, 2013, at 2:26 PM, "Marcus (OOo)" <ma...@wtnet.de>
> >> wrote:
> >> >>
> >> >> > Am 07/12/2013 07:18 PM, schrieb janI:
> >> >> >> On 12 July 2013 18:49, Rob Weir<ro...@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 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 Committer only wiki (???)
> >
> >
> >
> >>
> >> > 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.
> >
> >
> > yes...I agree. Sadly, I see the Install instructions are hardly used at
> > all, but I think "for the record", we need to have them.
> >
> >
> >
> >> 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.
> >>
> >
> > OK...
> >
> >
> >>
> >> > I, too, really don't like the idea of anyone with a wiki account being
> >> able
> >> > to change these, especially with the possibility of no general
> >> > consultation or consensus.
> >> >
> >>
> >> There are ways of handling this that control the ACL, such as using
> >> the OOODEV CWiki, or even using static HTML or MDText pages, if the
> >> open access of the wiki is a concern.
> >>
> >
> > I know about the OOODEV CWiki, -- I just never tried to access it.
> >
> > I'm OK with using that area for the Release Notes.
> >
> >
> >
> >> Regards,
> >>
> >> -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-unsubscribe@openoffice.apache.org
> >> >> > For additional commands, e-mail: dev-help@openoffice.apache.org
> >> >> >
> >> >>
> >> >> ---------------------------------------------------------------------
> >> >> To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
> >> >> For additional commands, e-mail: dev-help@openoffice.apache.org
> >> >>
> >> >>
> >> >
> >> >
> >> > --
> >> >
> >>
> -------------------------------------------------------------------------------------------------
> >> > MzK
> >> >
> >> > "Every day we should hear at least one little song,
> >> > read one good poem, see one exquisite picture,
> >> > and, if possible, speak a few sensible words."
> >> > -- Johann Wolfgang von Goethe
> >>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
> >> For additional commands, e-mail: dev-help@openoffice.apache.org
> >>
> >>
> >
> >
> > --
> >
> -------------------------------------------------------------------------------------------------
> > MzK
> >
> > "Every day we should hear at least one little song,
> > read one good poem, see one exquisite picture,
> > and, if possible, speak a few sensible words."
> > -- Johann Wolfgang von Goethe
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
> For additional commands, e-mail: dev-help@openoffice.apache.org
>
>
--
-------------------------------------------------------------------------------------------------
MzK
Success is falling nine times and getting up ten."
-- Jon Bon Jovi
Re: Where to keep release notes?
Posted by Rob Weir <ro...@apache.org>.
On Fri, Jul 12, 2013 at 7:54 PM, Kay Schenk <ka...@gmail.com> wrote:
> On Fri, Jul 12, 2013 at 4:45 PM, Rob Weir <ro...@apache.org> wrote:
>
>> On Fri, Jul 12, 2013 at 3:52 PM, Kay Schenk <ka...@gmail.com> wrote:
>> > On Fri, Jul 12, 2013 at 12:17 PM, Rob Weir <ra...@gmail.com> wrote:
>> >
>> >> On Jul 12, 2013, at 2:26 PM, "Marcus (OOo)" <ma...@wtnet.de>
>> wrote:
>> >>
>> >> > Am 07/12/2013 07:18 PM, schrieb janI:
>> >> >> On 12 July 2013 18:49, Rob Weir<ro...@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 Committer only wiki (???)
>
>
>
>>
>> > 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.
>
>
> yes...I agree. Sadly, I see the Install instructions are hardly used at
> all, but I think "for the record", we need to have them.
>
>
>
>> 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.
>>
>
> OK...
>
>
>>
>> > I, too, really don't like the idea of anyone with a wiki account being
>> able
>> > to change these, especially with the possibility of no general
>> > consultation or consensus.
>> >
>>
>> There are ways of handling this that control the ACL, such as using
>> the OOODEV CWiki, or even using static HTML or MDText pages, if the
>> open access of the wiki is a concern.
>>
>
> I know about the OOODEV CWiki, -- I just never tried to access it.
>
> I'm OK with using that area for the Release Notes.
>
>
>
>> Regards,
>>
>> -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-unsubscribe@openoffice.apache.org
>> >> > For additional commands, e-mail: dev-help@openoffice.apache.org
>> >> >
>> >>
>> >> ---------------------------------------------------------------------
>> >> To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
>> >> For additional commands, e-mail: dev-help@openoffice.apache.org
>> >>
>> >>
>> >
>> >
>> > --
>> >
>> -------------------------------------------------------------------------------------------------
>> > MzK
>> >
>> > "Every day we should hear at least one little song,
>> > read one good poem, see one exquisite picture,
>> > and, if possible, speak a few sensible words."
>> > -- Johann Wolfgang von Goethe
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
>> For additional commands, e-mail: dev-help@openoffice.apache.org
>>
>>
>
>
> --
> -------------------------------------------------------------------------------------------------
> MzK
>
> "Every day we should hear at least one little song,
> read one good poem, see one exquisite picture,
> and, if possible, speak a few sensible words."
> -- Johann Wolfgang von Goethe
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
Re: Where to keep release notes?
Posted by Kay Schenk <ka...@gmail.com>.
On Fri, Jul 12, 2013 at 4:45 PM, Rob Weir <ro...@apache.org> wrote:
> On Fri, Jul 12, 2013 at 3:52 PM, Kay Schenk <ka...@gmail.com> wrote:
> > On Fri, Jul 12, 2013 at 12:17 PM, Rob Weir <ra...@gmail.com> wrote:
> >
> >> On Jul 12, 2013, at 2:26 PM, "Marcus (OOo)" <ma...@wtnet.de>
> wrote:
> >>
> >> > Am 07/12/2013 07:18 PM, schrieb janI:
> >> >> On 12 July 2013 18:49, Rob Weir<ro...@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.
> 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 Committer only wiki (???)
>
> > 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.
yes...I agree. Sadly, I see the Install instructions are hardly used at
all, but I think "for the record", we need to have them.
> 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.
>
OK...
>
> > I, too, really don't like the idea of anyone with a wiki account being
> able
> > to change these, especially with the possibility of no general
> > consultation or consensus.
> >
>
> There are ways of handling this that control the ACL, such as using
> the OOODEV CWiki, or even using static HTML or MDText pages, if the
> open access of the wiki is a concern.
>
I know about the OOODEV CWiki, -- I just never tried to access it.
I'm OK with using that area for the Release Notes.
> Regards,
>
> -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-unsubscribe@openoffice.apache.org
> >> > For additional commands, e-mail: dev-help@openoffice.apache.org
> >> >
> >>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
> >> For additional commands, e-mail: dev-help@openoffice.apache.org
> >>
> >>
> >
> >
> > --
> >
> -------------------------------------------------------------------------------------------------
> > MzK
> >
> > "Every day we should hear at least one little song,
> > read one good poem, see one exquisite picture,
> > and, if possible, speak a few sensible words."
> > -- Johann Wolfgang von Goethe
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
> For additional commands, e-mail: dev-help@openoffice.apache.org
>
>
--
-------------------------------------------------------------------------------------------------
MzK
"Every day we should hear at least one little song,
read one good poem, see one exquisite picture,
and, if possible, speak a few sensible words."
-- Johann Wolfgang von Goethe
Re: Where to keep release notes?
Posted by "Marcus (OOo)" <ma...@wtnet.de>.
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-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
Re: Where to keep release notes?
Posted by "Marcus (OOo)" <ma...@wtnet.de>.
Am 07/13/2013 01:45 AM, schrieb Rob Weir:
> On Fri, Jul 12, 2013 at 3:52 PM, Kay Schenk<ka...@gmail.com> wrote:
>> On Fri, Jul 12, 2013 at 12:17 PM, Rob Weir<ra...@gmail.com> wrote:
>>
>>> On Jul 12, 2013, at 2:26 PM, "Marcus (OOo)"<ma...@wtnet.de> wrote:
>>>
>>>> Am 07/12/2013 07:18 PM, schrieb janI:
>>>>> On 12 July 2013 18:49, Rob Weir<ro...@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, especially with the possibility of no general
>> consultation or consensus.
>>
>
> There are ways of handling this that control the ACL, such as using
> the OOODEV CWiki, or even using static HTML or MDText pages, if the
> open access of the wiki is a concern.
For me yes, it is a concern that everybody could change a document that
shouldn't (mostly) be changed when the release is done. Of course
changes in the Wiki can be reverted (same for edits in SVN). But IMHO we
shouldn't rely on this just to be able to put text whereever we want.
So, if we could create a zone inside the Wiki with limited access, put
the release notes there and update only the sections for "Known Issues"
and others, when there is really a need for, then I would be OK to put
the complete release notes into the Wiki.
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.org
For additional commands, e-mail: dev-help@openoffice.apache.org
Re: Where to keep release notes?
Posted by Rob Weir <ro...@apache.org>.
On Fri, Jul 12, 2013 at 3:52 PM, Kay Schenk <ka...@gmail.com> wrote:
> On Fri, Jul 12, 2013 at 12:17 PM, Rob Weir <ra...@gmail.com> wrote:
>
>> On Jul 12, 2013, at 2:26 PM, "Marcus (OOo)" <ma...@wtnet.de> wrote:
>>
>> > Am 07/12/2013 07:18 PM, schrieb janI:
>> >> On 12 July 2013 18:49, Rob Weir<ro...@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, especially with the possibility of no general
> consultation or consensus.
>
There are ways of handling this that control the ACL, such as using
the OOODEV CWiki, or even using static HTML or MDText pages, if the
open access of the wiki is a concern.
Regards,
-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-unsubscribe@openoffice.apache.org
>> > For additional commands, e-mail: dev-help@openoffice.apache.org
>> >
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
>> For additional commands, e-mail: dev-help@openoffice.apache.org
>>
>>
>
>
> --
> -------------------------------------------------------------------------------------------------
> MzK
>
> "Every day we should hear at least one little song,
> read one good poem, see one exquisite picture,
> and, if possible, speak a few sensible words."
> -- Johann Wolfgang von Goethe
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
Re: Where to keep release notes?
Posted by Kay Schenk <ka...@gmail.com>.
On Fri, Jul 12, 2013 at 12:17 PM, Rob Weir <ra...@gmail.com> wrote:
> On Jul 12, 2013, at 2:26 PM, "Marcus (OOo)" <ma...@wtnet.de> wrote:
>
> > Am 07/12/2013 07:18 PM, schrieb janI:
> >> On 12 July 2013 18:49, Rob Weir<ro...@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
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, too, really don't like the idea of anyone with a wiki account being able
to change these, especially with the possibility of no general
consultation or consensus.
> > 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-unsubscribe@openoffice.apache.org
> > For additional commands, e-mail: dev-help@openoffice.apache.org
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
> For additional commands, e-mail: dev-help@openoffice.apache.org
>
>
--
-------------------------------------------------------------------------------------------------
MzK
"Every day we should hear at least one little song,
read one good poem, see one exquisite picture,
and, if possible, speak a few sensible words."
-- Johann Wolfgang von Goethe
Re: Where to keep release notes?
Posted by Rob Weir <ra...@gmail.com>.
On Jul 12, 2013, at 2:26 PM, "Marcus (OOo)" <ma...@wtnet.de> wrote:
> Am 07/12/2013 07:18 PM, schrieb janI:
>> On 12 July 2013 18:49, Rob Weir<ro...@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-unsubscribe@openoffice.apache.org
> For additional commands, e-mail: dev-help@openoffice.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
Re: Where to keep release notes?
Posted by "Marcus (OOo)" <ma...@wtnet.de>.
Am 07/12/2013 07:18 PM, schrieb janI:
> On 12 July 2013 18:49, Rob Weir<ro...@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-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
Re: Where to keep release notes?
Posted by Rob Weir <ra...@gmail.com>.
On Jul 12, 2013, at 1:18 PM, janI <ja...@apache.org> wrote:
> On 12 July 2013 18:49, Rob Weir <ro...@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-unsubscribe@openoffice.apache.org
>> For additional commands, e-mail: dev-help@openoffice.apache.org
>>
>>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@openoffice.apache.org
For additional commands, e-mail: dev-help@openoffice.apache.org
Re: Where to keep release notes?
Posted by janI <ja...@apache.org>.
On 12 July 2013 18:49, Rob Weir <ro...@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-unsubscribe@openoffice.apache.org
> For additional commands, e-mail: dev-help@openoffice.apache.org
>
>