ref-manual: reverse the order of migration guides?

ref-manual: reverse the order of migration guides?

[Michael Opdenacker]

Greetings,

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...

Thanks in advance,

Michael.

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

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

[Richard Purdie]

On Tue, 2021-04-13 at 20:03 +0200, Michael Opdenacker wrote:
> Greetings,
> 
> 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...

Yes, I think it would. When we made the migration to sphinx, I took the decision
to split these into their own files. This is a next logical step from that.

Cheers,

Richard

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

[Robert P. J. Day]

Quoting Richard Purdie <richard.purdie@linuxfoundation.org>:

> On Tue, 2021-04-13 at 20:03 +0200, Michael Opdenacker wrote:
>> Greetings,
>>
>> 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...
>
> Yes, I think it would. When we made the migration to sphinx, I took  
> the decision
> to split these into their own files. This is a next logical step from that.

   i'd go for moving all the migration stuff into its own manual ...
the reference manual is chock full as it is, there's no point making
it even larger with material that new users won't care about.

rday

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

[Paul Eggleton]

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.)

Cheers
Paul

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

[Nicolas Dechesne]

[-- 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 --]

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

[Michael Opdenacker]

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

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

[Michael Opdenacker]

Oops, sent to the wrong list (meant to use the "docs" list). You can
remove if this list is moderated.

Apologies

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

ref-manual: reverse the order of migration guides?

[Michael Opdenacker]

Greetings,

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...

Thanks in advance,

Michael.

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