openoffice-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rob Weir <robw...@apache.org>
Subject Re: Where to keep release notes?
Date Sat, 13 Jul 2013 22:17:11 GMT
On Fri, Jul 12, 2013 at 7:54 PM, Kay Schenk <kay.schenk@gmail.com> wrote:
> On Fri, Jul 12, 2013 at 4:45 PM, Rob Weir <robweir@apache.org> wrote:
>
>> On Fri, Jul 12, 2013 at 3:52 PM, Kay Schenk <kay.schenk@gmail.com> wrote:
>> > On Fri, Jul 12, 2013 at 12:17 PM, Rob Weir <rabastus@gmail.com> wrote:
>> >
>> >> On Jul 12, 2013, at 2:26 PM, "Marcus (OOo)" <marcus.mail@wtnet.de>
>> wrote:
>> >>
>> >> > Am 07/12/2013 07:18 PM, schrieb janI:
>> >> >> On 12 July 2013 18:49, Rob Weir<robweir@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


Mime
View raw message