[Ksummit-discuss] [TECH TOPIC] kernel documentation

[Ksummit-discuss] [TECH TOPIC] kernel documentation

[Daniel Vetter]

In 4.8 we have a shiny new kernel doc toolchain:

https://lwn.net/Articles/692705/

I think it'd be great if interested parties (might be just a hallway
track) sit together and figure out how to best go about converting all
the existing docs over, and how to link it all together. I think we
pretty much have agreement that the docbook horror show needs to die,
but there's lots of other documentation that I think would be great to
include in the overall (cross-linked!) kernel docs.

People who would be great to be there:
- Jon Corbet
- Mauro Carvalho
- Jani Nikula
- Markus Heiser
- maybe Grant Likely, he made noises about sphinx/rst too

I think converting/polishing docs would also serve well as kernel
newbie task in opw or gsoc or wherever, that might be another
interested group. And anyone else who wants to convert over docs for
their subsystem.

Mostly I'm just sending this out to gauge interest.

Cheers, Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch

Re: [Ksummit-discuss] [TECH TOPIC] kernel documentation

[Julia Lawall]

On Wed, 20 Jul 2016, Daniel Vetter wrote:

> In 4.8 we have a shiny new kernel doc toolchain:
>
> https://lwn.net/Articles/692705/
>
> I think it'd be great if interested parties (might be just a hallway
> track) sit together and figure out how to best go about converting all
> the existing docs over, and how to link it all together. I think we
> pretty much have agreement that the docbook horror show needs to die,
> but there's lots of other documentation that I think would be great to
> include in the overall (cross-linked!) kernel docs.
>
> People who would be great to be there:
> - Jon Corbet
> - Mauro Carvalho
> - Jani Nikula
> - Markus Heiser
> - maybe Grant Likely, he made noises about sphinx/rst too
>
> I think converting/polishing docs would also serve well as kernel
> newbie task in opw or gsoc or wherever, that might be another
> interested group. And anyone else who wants to convert over docs for
> their subsystem.

If anyone wants to mentor an outreachy intern on this topic, let me know.
There would be a new round of internships starting in December.

julia

Re: [Ksummit-discuss] [TECH TOPIC] kernel documentation

[Mauro Carvalho Chehab]

HI Daniel,

Em Wed, 20 Jul 2016 13:56:31 +0200
Daniel Vetter <daniel.vetter@ffwll.ch> escreveu:

> In 4.8 we have a shiny new kernel doc toolchain:
> 
> https://lwn.net/Articles/692705/
> 
> I think it'd be great if interested parties (might be just a hallway
> track) sit together and figure out how to best go about converting all
> the existing docs over, and how to link it all together. I think we
> pretty much have agreement that the docbook horror show needs to die,
> but there's lots of other documentation that I think would be great to
> include in the overall (cross-linked!) kernel docs.
> 
> People who would be great to be there:
> - Jon Corbet
> - Mauro Carvalho
> - Jani Nikula
> - Markus Heiser
> - maybe Grant Likely, he made noises about sphinx/rst too
> 
> I think converting/polishing docs would also serve well as kernel
> newbie task in opw or gsoc or wherever, that might be another
> interested group. And anyone else who wants to convert over docs for
> their subsystem.
> 
> Mostly I'm just sending this out to gauge interest.

Yeah, I think we should do it. Just not sure if this is a TECH
TOPIC or a CORE one ;) Documentation will sooner or later touch
all subsystems.  So, I guess we should at least highlight some
things to the core group (Or at least do a lightning talk there).

Yet, a TECH topic would be interesting for us to discuss some
details about that.

Regards,
Mauro

Re: [Ksummit-discuss] [TECH TOPIC] kernel documentation

[Jonathan Corbet]

On Wed, 20 Jul 2016 13:56:31 +0200
Daniel Vetter <daniel.vetter@ffwll.ch> wrote:

> I think it'd be great if interested parties (might be just a hallway
> track) sit together and figure out how to best go about converting all
> the existing docs over, and how to link it all together.

I had thought about proposing a similar topic.  I think it could also be
useful to have a brief session on how the new stuff works.

jon

Re: [Ksummit-discuss] [TECH TOPIC] kernel documentation

[Laurent Pinchart]

On Wednesday 20 Jul 2016 17:10:26 Jonathan Corbet wrote:
> On Wed, 20 Jul 2016 13:56:31 +0200 Daniel Vetter wrote:
> > I think it'd be great if interested parties (might be just a hallway
> > track) sit together and figure out how to best go about converting all
> > the existing docs over, and how to link it all together.
> 
> I had thought about proposing a similar topic.  I think it could also be
> useful to have a brief session on how the new stuff works.

I'd be more interested in that than in a session that discusses the process of 
converting existing documentation. It's up to each subsystem to move away from 
DocBook, I don't really see what we would have to discuss there.

That being said, in order to make the documentation consistent, we'll need 
some level of bikeshedding to decide on guidelines for maintainers and 
developers. I don't want to spend the kernel summit bikeshedding, but maybe a 
high-level discussion on what we need could be useful.

-- 
Regards,

Laurent Pinchart

Re: [Ksummit-discuss] [TECH TOPIC] kernel documentation

[Johannes Berg]

On Wed, 2016-07-20 at 17:10 -0600, Jonathan Corbet wrote:
> 
> I think it could also be useful to have a brief session on how the
> new stuff works.
> 

That would be nice; the LWN article was very useful, but seeing it
hands-on would help I think.

Not sure that should really be in KS though.

johannes

Re: [Ksummit-discuss] [TECH TOPIC] kernel documentation

[Jani Nikula]

On Wed, 20 Jul 2016, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> In 4.8 we have a shiny new kernel doc toolchain:
>
> https://lwn.net/Articles/692705/
>
> I think it'd be great if interested parties (might be just a hallway
> track) sit together and figure out how to best go about converting all
> the existing docs over, and how to link it all together. I think we
> pretty much have agreement that the docbook horror show needs to die,
> but there's lots of other documentation that I think would be great to
> include in the overall (cross-linked!) kernel docs.
>
> People who would be great to be there:
> - Jon Corbet
> - Mauro Carvalho
> - Jani Nikula
> - Markus Heiser
> - maybe Grant Likely, he made noises about sphinx/rst too
>
> I think converting/polishing docs would also serve well as kernel
> newbie task in opw or gsoc or wherever, that might be another
> interested group. And anyone else who wants to convert over docs for
> their subsystem.
>
> Mostly I'm just sending this out to gauge interest.

Perhaps this is redundant, but for the record, I'm interested.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center