* Modern style documentation
@ 2020-06-24 14:05 marius.kriegerowski
2020-06-24 14:23 ` [docs] " Richard Purdie
0 siblings, 1 reply; 8+ messages in thread
From: marius.kriegerowski @ 2020-06-24 14:05 UTC (permalink / raw
To: docs@lists.yoctoproject.org
[-- Attachment #1: Type: text/plain, Size: 931 bytes --]
Dear Community,
I would like to motivate a re-structuring of the documentation. The single page documenting mega manual is great as it carries all the information. But at the same time it is hard to navigate, overwhelming for early stage users and hard to pick up where started earlier on.
Are there plans that break this single page documentation?
To be more constructive: I find it very convenient and I highly recommend a permanently shown navigation bar, highlighting where the current content is located. This allows to find information again, even if a user only has a vague idea where a piece of information was found last time, simply thanks to the iinherent structural pattern, not only the text describing the chapters. Let's take advantage of the humans being better at remembering shapes and patterns rather than text and content.
If this undertaking is already on it's way I'd be happy to join.
Best regards
Marius
[-- Attachment #2: Type: text/html, Size: 1099 bytes --]
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [docs] Modern style documentation
2020-06-24 14:05 Modern style documentation marius.kriegerowski
@ 2020-06-24 14:23 ` Richard Purdie
2020-06-24 14:27 ` Nicolas Dechesne
0 siblings, 1 reply; 8+ messages in thread
From: Richard Purdie @ 2020-06-24 14:23 UTC (permalink / raw
To: marius.kriegerowski, docs@lists.yoctoproject.org
Hi,
On Wed, 2020-06-24 at 14:05 +0000, Marius Kriegerowski via
lists.yoctoproject.org wrote:
>
> Dear Community,
> I would like to motivate a re-structuring of the documentation. The
> single page documenting mega manual is great as it carries all the
> information. But at the same time it is hard to navigate,
> overwhelming for early stage users and hard to pick up where started
> earlier on.
> Are there plans that break this single page documentation?
>
> To be more constructive: I find it very convenient and I highly
> recommend a permanently shown navigation bar, highlighting where the
> current content is located. This allows to find information again,
> even if a user only has a vague idea where a piece of information was
> found last time, simply thanks to the iinherent structural pattern,
> not only the text describing the chapters. Let's take advantage of
> the humans being better at remembering shapes and patterns rather
> than text and content.
>
> If this undertaking is already on it's way I'd be happy to join.
I did notice the discussion on irc.
FWIW we're in the middle of planning to migrate the documentation from
its current format in docbook over to sphinx. I think that should give
us more options for what you describe with navigation in amongst
various other advantages.
Help with the migration would be much appreciated and we'll keep this
need in mind as we work through the details of this.
I do think we'll end up with some kind of combination of both formats
since some people do need something searchable/scrollable but I realise
others need the navigation interface more, there is a place/need for
both.
Cheers,
Richard
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [docs] Modern style documentation
2020-06-24 14:23 ` [docs] " Richard Purdie
@ 2020-06-24 14:27 ` Nicolas Dechesne
2020-06-25 17:37 ` akuster
0 siblings, 1 reply; 8+ messages in thread
From: Nicolas Dechesne @ 2020-06-24 14:27 UTC (permalink / raw
To: Richard Purdie; +Cc: marius.kriegerowski, docs@lists.yoctoproject.org
On Wed, Jun 24, 2020 at 4:23 PM Richard Purdie
<richard.purdie@linuxfoundation.org> wrote:
>
> Hi,
>
> On Wed, 2020-06-24 at 14:05 +0000, Marius Kriegerowski via
> lists.yoctoproject.org wrote:
> >
> > Dear Community,
> > I would like to motivate a re-structuring of the documentation. The
> > single page documenting mega manual is great as it carries all the
> > information. But at the same time it is hard to navigate,
> > overwhelming for early stage users and hard to pick up where started
> > earlier on.
> > Are there plans that break this single page documentation?
> >
> > To be more constructive: I find it very convenient and I highly
> > recommend a permanently shown navigation bar, highlighting where the
> > current content is located. This allows to find information again,
> > even if a user only has a vague idea where a piece of information was
> > found last time, simply thanks to the iinherent structural pattern,
> > not only the text describing the chapters. Let's take advantage of
> > the humans being better at remembering shapes and patterns rather
> > than text and content.
> >
> > If this undertaking is already on it's way I'd be happy to join.
>
> I did notice the discussion on irc.
>
> FWIW we're in the middle of planning to migrate the documentation from
> its current format in docbook over to sphinx. I think that should give
> us more options for what you describe with navigation in amongst
> various other advantages.
>
> Help with the migration would be much appreciated and we'll keep this
> need in mind as we work through the details of this.
>
> I do think we'll end up with some kind of combination of both formats
> since some people do need something searchable/scrollable but I realise
> others need the navigation interface more, there is a place/need for
> both.
FWIW. you can check our current work-in-progress thoughts on this topic here:
https://wiki.yoctoproject.org/wiki/index.php?title=Documentation_Sphinx
>
> Cheers,
>
> Richard
>
>
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [docs] Modern style documentation
2020-06-24 14:27 ` Nicolas Dechesne
@ 2020-06-25 17:37 ` akuster
2020-06-26 8:12 ` Nicolas Dechesne
0 siblings, 1 reply; 8+ messages in thread
From: akuster @ 2020-06-25 17:37 UTC (permalink / raw
To: Nicolas Dechesne, Richard Purdie
Cc: marius.kriegerowski, docs@lists.yoctoproject.org
[-- Attachment #1: Type: text/plain, Size: 2538 bytes --]
Hello,
On 6/24/20 7:27 AM, Nicolas Dechesne wrote:
> On Wed, Jun 24, 2020 at 4:23 PM Richard Purdie
> <richard.purdie@linuxfoundation.org> wrote:
>> Hi,
>>
>> On Wed, 2020-06-24 at 14:05 +0000, Marius Kriegerowski via
>> lists.yoctoproject.org wrote:
>>> Dear Community,
>>> I would like to motivate a re-structuring of the documentation. The
>>> single page documenting mega manual is great as it carries all the
>>> information. But at the same time it is hard to navigate,
>>> overwhelming for early stage users and hard to pick up where started
>>> earlier on.
>>> Are there plans that break this single page documentation?
>>>
>>> To be more constructive: I find it very convenient and I highly
>>> recommend a permanently shown navigation bar, highlighting where the
>>> current content is located. This allows to find information again,
>>> even if a user only has a vague idea where a piece of information was
>>> found last time, simply thanks to the iinherent structural pattern,
>>> not only the text describing the chapters. Let's take advantage of
>>> the humans being better at remembering shapes and patterns rather
>>> than text and content.
>>>
>>> If this undertaking is already on it's way I'd be happy to join.
Sorry I missed the meeting. I had a conflict with an internal meeting.
One thing I would like to add to the things to look into is the ability to:
1) Build documentation via a recipe
2) Include documention in an SDK
#1 is more for Build automation checkout etc and is needed for #2
I realize this may be a meta-poky thing only.
Are there any other meeting scheduled?
- armin
>> I did notice the discussion on irc.
>>
>> FWIW we're in the middle of planning to migrate the documentation from
>> its current format in docbook over to sphinx. I think that should give
>> us more options for what you describe with navigation in amongst
>> various other advantages.
>>
>> Help with the migration would be much appreciated and we'll keep this
>> need in mind as we work through the details of this.
>>
>> I do think we'll end up with some kind of combination of both formats
>> since some people do need something searchable/scrollable but I realise
>> others need the navigation interface more, there is a place/need for
>> both.
> FWIW. you can check our current work-in-progress thoughts on this topic here:
> https://wiki.yoctoproject.org/wiki/index.php?title=Documentation_Sphinx
>
>
>> Cheers,
>>
>> Richard
>>
>>
>>
>>
[-- Attachment #2: Type: text/html, Size: 3872 bytes --]
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [docs] Modern style documentation
2020-06-25 17:37 ` akuster
@ 2020-06-26 8:12 ` Nicolas Dechesne
2020-06-26 8:15 ` Richard Purdie
2020-06-27 18:29 ` akuster
0 siblings, 2 replies; 8+ messages in thread
From: Nicolas Dechesne @ 2020-06-26 8:12 UTC (permalink / raw
To: akuster808
Cc: Richard Purdie, marius.kriegerowski, docs@lists.yoctoproject.org
[-- Attachment #1: Type: text/plain, Size: 3025 bytes --]
On Thu, Jun 25, 2020 at 7:37 PM akuster808 <akuster808@gmail.com> wrote:
> Hello,
>
>
> On 6/24/20 7:27 AM, Nicolas Dechesne wrote:
>
> On Wed, Jun 24, 2020 at 4:23 PM Richard Purdie<richard.purdie@linuxfoundation.org> <richard.purdie@linuxfoundation.org> wrote:
>
> Hi,
>
> On Wed, 2020-06-24 at 14:05 +0000, Marius Kriegerowski vialists.yoctoproject.org wrote:
>
> Dear Community,
> I would like to motivate a re-structuring of the documentation. The
> single page documenting mega manual is great as it carries all the
> information. But at the same time it is hard to navigate,
> overwhelming for early stage users and hard to pick up where started
> earlier on.
> Are there plans that break this single page documentation?
>
> To be more constructive: I find it very convenient and I highly
> recommend a permanently shown navigation bar, highlighting where the
> current content is located. This allows to find information again,
> even if a user only has a vague idea where a piece of information was
> found last time, simply thanks to the iinherent structural pattern,
> not only the text describing the chapters. Let's take advantage of
> the humans being better at remembering shapes and patterns rather
> than text and content.
>
> If this undertaking is already on it's way I'd be happy to join.
>
> Sorry I missed the meeting. I had a conflict with an internal meeting.
>
> One thing I would like to add to the things to look into is the ability to:
>
> 1) Build documentation via a recipe
>
2) Include documention in an SDK
>
>
> #1 is more for Build automation checkout etc and is needed for #2
>
> I realize this may be a meta-poky thing only.
>
Can you elaborate on what you are asking here? A recipe would need to
'fetch' the document sources with a fixed SRCREV. Or do you want to build
the 'current' set of files from the documentation folder?
> Are there any other meeting scheduled?
>
Not at this point of time. I believe the next step was discussion/agreement
from the TSC. and once that is done, we will start pushing a sphinx branch
and hack on it.
>
>
>
> - armin
>
> I did notice the discussion on irc.
>
> FWIW we're in the middle of planning to migrate the documentation from
> its current format in docbook over to sphinx. I think that should give
> us more options for what you describe with navigation in amongst
> various other advantages.
>
> Help with the migration would be much appreciated and we'll keep this
> need in mind as we work through the details of this.
>
> I do think we'll end up with some kind of combination of both formats
> since some people do need something searchable/scrollable but I realise
> others need the navigation interface more, there is a place/need for
> both.
>
> FWIW. you can check our current work-in-progress thoughts on this topic here:https://wiki.yoctoproject.org/wiki/index.php?title=Documentation_Sphinx
>
> Cheers,
>
> Richard
>
>
>
>
>
>
>
>
[-- Attachment #2: Type: text/html, Size: 4675 bytes --]
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [docs] Modern style documentation
2020-06-26 8:12 ` Nicolas Dechesne
@ 2020-06-26 8:15 ` Richard Purdie
2020-06-27 18:29 ` akuster
1 sibling, 0 replies; 8+ messages in thread
From: Richard Purdie @ 2020-06-26 8:15 UTC (permalink / raw
To: Nicolas Dechesne, akuster808
Cc: marius.kriegerowski, docs@lists.yoctoproject.org
On Fri, 2020-06-26 at 10:12 +0200, Nicolas Dechesne wrote:
>
>
> On Thu, Jun 25, 2020 at 7:37 PM akuster808 <akuster808@gmail.com>
> wrote:
> > Hello,
> >
> >
> > On 6/24/20 7:27 AM, Nicolas Dechesne wrote:
> > > On Wed, Jun 24, 2020 at 4:23 PM Richard Purdie
> > > <richard.purdie@linuxfoundation.org> wrote:
> > > > Hi,
> > > >
> > > > On Wed, 2020-06-24 at 14:05 +0000, Marius Kriegerowski via
> > > > lists.yoctoproject.org wrote:
> > > > > Dear Community,
> > > > > I would like to motivate a re-structuring of the
> > > > > documentation. The
> > > > > single page documenting mega manual is great as it carries
> > > > > all the
> > > > > information. But at the same time it is hard to navigate,
> > > > > overwhelming for early stage users and hard to pick up where
> > > > > started
> > > > > earlier on.
> > > > > Are there plans that break this single page documentation?
> > > > >
> > > > > To be more constructive: I find it very convenient and I
> > > > > highly
> > > > > recommend a permanently shown navigation bar, highlighting
> > > > > where the
> > > > > current content is located. This allows to find information
> > > > > again,
> > > > > even if a user only has a vague idea where a piece of
> > > > > information was
> > > > > found last time, simply thanks to the iinherent structural
> > > > > pattern,
> > > > > not only the text describing the chapters. Let's take
> > > > > advantage of
> > > > > the humans being better at remembering shapes and patterns
> > > > > rather
> > > > > than text and content.
> > > > >
> > > > > If this undertaking is already on it's way I'd be happy to
> > > > > join.
> > Sorry I missed the meeting. I had a conflict with an internal
> > meeting.
> >
> > One thing I would like to add to the things to look into is the
> > ability to:
> >
> > 1) Build documentation via a recipe
> >
> > 2) Include documention in an SDK
> >
> >
> > #1 is more for Build automation checkout etc and is needed for #2
> >
> > I realize this may be a meta-poky thing only.
> >
>
> Can you elaborate on what you are asking here? A recipe would need to
> 'fetch' the document sources with a fixed SRCREV. Or do you want to
> build the 'current' set of files from the documentation folder?
>
> > Are there any other meeting scheduled?
> >
>
> Not at this point of time. I believe the next step was
> discussion/agreement from the TSC. and once that is done, we will
> start pushing a sphinx branch and hack on it.
The TSC has discussed/agreed with direction so we can start with the
branch...
Cheers,
Richard
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [docs] Modern style documentation
2020-06-26 8:12 ` Nicolas Dechesne
2020-06-26 8:15 ` Richard Purdie
@ 2020-06-27 18:29 ` akuster
2020-06-29 6:01 ` Nicolas Dechesne
1 sibling, 1 reply; 8+ messages in thread
From: akuster @ 2020-06-27 18:29 UTC (permalink / raw
To: Nicolas Dechesne
Cc: Richard Purdie, marius.kriegerowski, docs@lists.yoctoproject.org
[-- Attachment #1: Type: text/plain, Size: 3666 bytes --]
On 6/26/20 1:12 AM, Nicolas Dechesne wrote:
>
>
> On Thu, Jun 25, 2020 at 7:37 PM akuster808 <akuster808@gmail.com
> <mailto:akuster808@gmail.com>> wrote:
>
> Hello,
>
>
> On 6/24/20 7:27 AM, Nicolas Dechesne wrote:
>> On Wed, Jun 24, 2020 at 4:23 PM Richard Purdie
>> <richard.purdie@linuxfoundation.org> <mailto:richard.purdie@linuxfoundation.org> wrote:
>>> Hi,
>>>
>>> On Wed, 2020-06-24 at 14:05 +0000, Marius Kriegerowski via
>>> lists.yoctoproject.org <http://lists.yoctoproject.org> wrote:
>>>> Dear Community,
>>>> I would like to motivate a re-structuring of the documentation. The
>>>> single page documenting mega manual is great as it carries all the
>>>> information. But at the same time it is hard to navigate,
>>>> overwhelming for early stage users and hard to pick up where started
>>>> earlier on.
>>>> Are there plans that break this single page documentation?
>>>>
>>>> To be more constructive: I find it very convenient and I highly
>>>> recommend a permanently shown navigation bar, highlighting where the
>>>> current content is located. This allows to find information again,
>>>> even if a user only has a vague idea where a piece of information was
>>>> found last time, simply thanks to the iinherent structural pattern,
>>>> not only the text describing the chapters. Let's take advantage of
>>>> the humans being better at remembering shapes and patterns rather
>>>> than text and content.
>>>>
>>>> If this undertaking is already on it's way I'd be happy to join.
> Sorry I missed the meeting. I had a conflict with an internal meeting.
>
> One thing I would like to add to the things to look into is the
> ability to:
>
> 1) Build documentation via a recipe
>
> 2) Include documention in an SDK
>
>
> #1 is more for Build automation checkout etc and is needed for #2
>
> I realize this may be a meta-poky thing only.
>
>
> Can you elaborate on what you are asking here? A recipe would need to
> 'fetch' the document sources with a fixed SRCREV. Or do you want to
> build the 'current' set of files from the documentation folder?
Why not build the docs during core-image-minimal??? and yeah, the Docs
are in their own repo so one could have a recipe to build the docs.
Someone could do that today.
-armin
>
>
> Are there any other meeting scheduled?
>
>
> Not at this point of time. I believe the next step was
> discussion/agreement from the TSC. and once that is done, we will
> start pushing a sphinx branch and hack on it.
>
>
>
>
>
> - armin
>>> I did notice the discussion on irc.
>>>
>>> FWIW we're in the middle of planning to migrate the documentation from
>>> its current format in docbook over to sphinx. I think that should give
>>> us more options for what you describe with navigation in amongst
>>> various other advantages.
>>>
>>> Help with the migration would be much appreciated and we'll keep this
>>> need in mind as we work through the details of this.
>>>
>>> I do think we'll end up with some kind of combination of both formats
>>> since some people do need something searchable/scrollable but I realise
>>> others need the navigation interface more, there is a place/need for
>>> both.
>> FWIW. you can check our current work-in-progress thoughts on this topic here:
>> https://wiki.yoctoproject.org/wiki/index.php?title=Documentation_Sphinx
>>
>>
>>> Cheers,
>>>
>>> Richard
>>>
>>>
>>>
>>>
>
[-- Attachment #2: Type: text/html, Size: 6630 bytes --]
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [docs] Modern style documentation
2020-06-27 18:29 ` akuster
@ 2020-06-29 6:01 ` Nicolas Dechesne
0 siblings, 0 replies; 8+ messages in thread
From: Nicolas Dechesne @ 2020-06-29 6:01 UTC (permalink / raw
To: akuster808
Cc: Richard Purdie, marius.kriegerowski, docs@lists.yoctoproject.org
[-- Attachment #1: Type: text/plain, Size: 4264 bytes --]
On Sat, Jun 27, 2020 at 8:30 PM akuster808 <akuster808@gmail.com> wrote:
>
>
> On 6/26/20 1:12 AM, Nicolas Dechesne wrote:
>
>
>
> On Thu, Jun 25, 2020 at 7:37 PM akuster808 <akuster808@gmail.com> wrote:
>
>> Hello,
>>
>>
>> On 6/24/20 7:27 AM, Nicolas Dechesne wrote:
>>
>> On Wed, Jun 24, 2020 at 4:23 PM Richard Purdie<richard.purdie@linuxfoundation.org> <richard.purdie@linuxfoundation.org> wrote:
>>
>> Hi,
>>
>> On Wed, 2020-06-24 at 14:05 +0000, Marius Kriegerowski vialists.yoctoproject.org wrote:
>>
>> Dear Community,
>> I would like to motivate a re-structuring of the documentation. The
>> single page documenting mega manual is great as it carries all the
>> information. But at the same time it is hard to navigate,
>> overwhelming for early stage users and hard to pick up where started
>> earlier on.
>> Are there plans that break this single page documentation?
>>
>> To be more constructive: I find it very convenient and I highly
>> recommend a permanently shown navigation bar, highlighting where the
>> current content is located. This allows to find information again,
>> even if a user only has a vague idea where a piece of information was
>> found last time, simply thanks to the iinherent structural pattern,
>> not only the text describing the chapters. Let's take advantage of
>> the humans being better at remembering shapes and patterns rather
>> than text and content.
>>
>> If this undertaking is already on it's way I'd be happy to join.
>>
>> Sorry I missed the meeting. I had a conflict with an internal meeting.
>>
>> One thing I would like to add to the things to look into is the ability
>> to:
>>
>> 1) Build documentation via a recipe
>>
> 2) Include documention in an SDK
>>
>>
>> #1 is more for Build automation checkout etc and is needed for #2
>>
>> I realize this may be a meta-poky thing only.
>>
>
> Can you elaborate on what you are asking here? A recipe would need to
> 'fetch' the document sources with a fixed SRCREV. Or do you want to build
> the 'current' set of files from the documentation folder?
>
>
> Why not build the docs during core-image-minimal??? and yeah, the Docs
> are in their own repo so one could have a recipe to build the docs.
> Someone could do that today.
>
yes, it's simple to have a recipe. I was asking how we want to keep the
recipe up-to-date. I think that having a yocto-docs_git.bb recipe would
give the illusion that it creates the up-to-date documentation, so that
means we will have to keep changing SRCREV in the doc recipe...
if you build from oe-core+bitbake that might look ok, but if you build from
poky then you have a copy of the documentation in your workspace, but it's
not the one used when running bitbake yocto-docs.
I still like the idea though of building the docs with a recipe.. that
means we will have to move the following recipes (at least for now) into
oe-core since they are needed:
http://layers.openembedded.org/layerindex/recipe/105896/
http://layers.openembedded.org/layerindex/recipe/39741/
> -armin
>
>
>
>> Are there any other meeting scheduled?
>>
>
> Not at this point of time. I believe the next step was
> discussion/agreement from the TSC. and once that is done, we will start
> pushing a sphinx branch and hack on it.
>
>
>>
>>
>>
>> - armin
>>
>> I did notice the discussion on irc.
>>
>> FWIW we're in the middle of planning to migrate the documentation from
>> its current format in docbook over to sphinx. I think that should give
>> us more options for what you describe with navigation in amongst
>> various other advantages.
>>
>> Help with the migration would be much appreciated and we'll keep this
>> need in mind as we work through the details of this.
>>
>> I do think we'll end up with some kind of combination of both formats
>> since some people do need something searchable/scrollable but I realise
>> others need the navigation interface more, there is a place/need for
>> both.
>>
>> FWIW. you can check our current work-in-progress thoughts on this topic here:https://wiki.yoctoproject.org/wiki/index.php?title=Documentation_Sphinx
>>
>> Cheers,
>>
>> Richard
>>
>>
>>
>>
>>
>>
>>
>>
>
[-- Attachment #2: Type: text/html, Size: 7735 bytes --]
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2020-06-29 6:01 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-06-24 14:05 Modern style documentation marius.kriegerowski
2020-06-24 14:23 ` [docs] " Richard Purdie
2020-06-24 14:27 ` Nicolas Dechesne
2020-06-25 17:37 ` akuster
2020-06-26 8:12 ` Nicolas Dechesne
2020-06-26 8:15 ` Richard Purdie
2020-06-27 18:29 ` akuster
2020-06-29 6:01 ` Nicolas Dechesne
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.