Re: [docs] ref-manual: reverse the order of migration guides?

From: "Nicolas Dechesne" <nicolas.dechesne@linaro.org>
To: Paul Eggleton <bluelightning@bluelightning.org>
Cc: YP docs mailing list <docs@lists.yoctoproject.org>,
	 Michael Opdenacker <michael.opdenacker@bootlin.com>,
	"Robert P. J. Day" <rpjday@crashcourse.ca>,
	 "Tummalapalli, Vineela" <vineela.tummalapalli@intel.com>,
	 Richard Purdie <richard.purdie@linuxfoundation.org>
Subject: Re: [docs] ref-manual: reverse the order of migration guides?
Date: Wed, 14 Apr 2021 07:33:41 +0200	[thread overview]
Message-ID: <CAP71WjzS-a9MNtyDeOwDV6oqhp8mNpNWmnoeuUyf2w_Qu+t2gg@mail.gmail.com> (raw)
In-Reply-To: <4706379.0VBMTVartN@linc>

[-- Attachment #1: Type: text/plain, Size: 2064 bytes --]

On Wed, Apr 14, 2021 at 2:15 AM Paul Eggleton <
bluelightning@bluelightning.org> wrote:

> Hi Michael
>
> On Wednesday, 14 April 2021 06:03:26 NZST Michael Opdenacker wrote:
> > Wouldn't it make sense to reverse the order of migration guides in the
> > reference manual
> > (
> https://www.yoctoproject.org/docs/3.0/ref-manual/ref-manual.html#migration
> )
> > ?
> >
> > I guess it would be easier to start mentioning the migration path from
> > the most recent release, as version 1.3 looks ancient.
> >
> > Would it make sense? If so, it's easy to propose a patch...
>
> I guess the thinking was that you would start at the point in the
> documentation where you are currently at and then follow it downwards to
> the
> current version. Whether that's the most logical I'm not sure, but if
> we're
> changing it we should give some thought to how it will be used. People do
> often go a while between upgrades, but I'll definitely agree 1.3 is much
> further back than most people would need.
>
> Robert suggests moving it out, I'm wondering if it's worth considering
> going a
> step further and turning our release notes into a proper document, to
> which
> this content would be added - I've often felt that the current text-only
> format is a bit restrictive. That would mean there would be a separate
> document per release, which is how many other software packages do it
> (e.g.
> Django). However, I'm not sure if that would cause us too much overhead or
> hassle with the other places where we currently post the release notes
> e.g.
> announcements on the mailing list - thoughts? (For clarity I wouldn't
> propose
> changing this until the next release.)
>

I have had this thought already, and like it! Especially now that we have a
'unified' doc website, having a 'release notes' manual/section in the left
side navigation bar would be good. Here is an example I have seen with
another project:
https://projectacrn.github.io/latest/release_notes/index.html

>
> Cheers
> Paul
>
>
>
> 
>
>

[-- Attachment #2: Type: text/html, Size: 2896 bytes --]