From dev-return-38502-apmail-openoffice-dev-archive=openoffice.apache.org@openoffice.apache.org Fri Jul 12 23:33:57 2013 Return-Path: X-Original-To: apmail-openoffice-dev-archive@www.apache.org Delivered-To: apmail-openoffice-dev-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 1334410494 for ; Fri, 12 Jul 2013 23:33:57 +0000 (UTC) Received: (qmail 30278 invoked by uid 500); 12 Jul 2013 23:33:56 -0000 Delivered-To: apmail-openoffice-dev-archive@openoffice.apache.org Received: (qmail 30210 invoked by uid 500); 12 Jul 2013 23:33:56 -0000 Mailing-List: contact dev-help@openoffice.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@openoffice.apache.org Delivered-To: mailing list dev@openoffice.apache.org Received: (qmail 30202 invoked by uid 99); 12 Jul 2013 23:33:56 -0000 Received: from minotaur.apache.org (HELO minotaur.apache.org) (140.211.11.9) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 12 Jul 2013 23:33:56 +0000 Received: from localhost (HELO mail-pb0-f43.google.com) (127.0.0.1) (smtp-auth username robweir, mechanism plain) by minotaur.apache.org (qpsmtpd/0.29) with ESMTP; Fri, 12 Jul 2013 23:33:56 +0000 Received: by mail-pb0-f43.google.com with SMTP id md12so9478881pbc.16 for ; Fri, 12 Jul 2013 16:33:56 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20120113; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :content-type; bh=DaS1UcE6oRQS+htKRiWqjngT3O3JqivnIgvuegcH6TY=; b=TT8Hv0mG2twsVk8zYte5blprFvO8nl4wefXjoN09Sxaxq5iN5/EI7fgU+YfroHpzjO I132LTWHwzxW3pWMnUHeKCHHEcGxMf5Wo4a0L+uKe64127c0RI11GDyjGDYGPv7V4uSt 1XQ8E845PU3XqEDm6LjdZIAVcnOSI7YMNGTc/ZJRp+Ig9zC1A4506a694cPemcRA2Sd+ SW4ZxTpeRGPVHKHSHZK2zfUCu3ZQ1S/PdXaJufa2e9zhB/+zT+l2i9Y/HJK78aEpnNQf uYAKgUIX4Lc6bFdoyaasrO90jvzjDAO2QCSqemnhNyTxpHmvJB4IqF5okk/raasU2O7D z9Gg== MIME-Version: 1.0 X-Received: by 10.66.27.169 with SMTP id u9mr31627372pag.130.1373672036051; Fri, 12 Jul 2013 16:33:56 -0700 (PDT) Received: by 10.70.89.195 with HTTP; Fri, 12 Jul 2013 16:33:55 -0700 (PDT) In-Reply-To: References: <51E04A25.2050507@wtnet.de> <3167418804279821258@unknownmsgid> <51E06A96.70400@wtnet.de> Date: Fri, 12 Jul 2013 19:33:55 -0400 Message-ID: Subject: Re: Where to keep release notes? From: Rob Weir To: "dev@openoffice.apache.org" Content-Type: text/plain; charset=UTF-8 On Fri, Jul 12, 2013 at 5:39 PM, janI wrote: > On 12 July 2013 22:44, Marcus (OOo) wrote: > >> Am 07/12/2013 09:17 PM, schrieb Rob Weir: >> >> On Jul 12, 2013, at 2:26 PM, "Marcus (OOo)" wrote: >>> >>> Am 07/12/2013 07:18 PM, schrieb janI: >>>> >>>>> On 12 July 2013 18:49, Rob Weir 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. ;-) > > > 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 >> 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