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

From: "Michael Opdenacker" <michael.opdenacker@bootlin.com>
To: Nicolas Dechesne <nicolas.dechesne@linaro.org>,
	Paul Eggleton <bluelightning@bluelightning.org>
Cc: YP docs mailing list <docs@lists.yoctoproject.org>,
	"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 09:34:31 +0200	[thread overview]
Message-ID: <274c25bd-700e-2ab1-22b5-c074b9d9fd4d@bootlin.com> (raw)
In-Reply-To: <CAP71WjzS-a9MNtyDeOwDV6oqhp8mNpNWmnoeuUyf2w_Qu+t2gg@mail.gmail.com>

Greetings,

On 4/14/21 7:33 AM, Nicolas Dechesne wrote:
>
>
> On Wed, Apr 14, 2021 at 2:15 AM Paul Eggleton
> <bluelightning@bluelightning.org
> <mailto:bluelightning@bluelightning.org>> wrote:
>
>
>
>     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
> <https://projectacrn.github.io/latest/release_notes/index.html>

I definitely vote for this. This would make our documentation much
easier to use.

Cheers,

Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com