[Ksummit-discuss] Kernel documentation discussions

[Mauro Carvalho Chehab <mchehab@infradead.org>]

Hi Jon,

As I wake up too early today, due to the time zone differences, and inspired
by your article about documentation at lwn (https://lwn.net/Articles/704613/),
I decided to take some time and do some brain storming to help with 
the KS discussions. Feel free to pick the good things here, and discard 
the rest ;)

This is based on the work I've doing on the past few months with
the media conversion, and, mainly my work with regards to development
process and admin guides. Btw, I wrote some articles to document
the challenges on those two books that might be interesting for the
discussions too:
	https://blogs.s-osg.org/creation-linux-kernel-users-manual/
	https://blogs.s-osg.org/documenting-linux-kernel-development-process/

They're part of an attempt from my side As to document the challenges 
I'm having with the documentation conversion:
	https://blogs.s-osg.org/new-improved-linux-kernel-media-documentation/

I'm c/c Greg, as I listed several things related to the ABI documentation.

ReST conversion - some stats
============================

If I got it right, this is the current status

	- about 600 files on ReST
	- 305 ABI files + ABI/README
	- 32 files with translations to Japanase, Korean and Chinese;
	- 30 files on DocBook
	- about 6k plain files to be converted, being 97 files at the
	  Documentation/ root directory (96 after EDAC conversion,
	  with I did already).

There's still an elephant at the room: who will do the remaining
conversions :)

Items requiring some sort of definition
=======================================

(probably, we won't have time on KS regular time to discuss all of them)

Please notice that this is a brainstorm list, with items I remembered,
with no particular order.

1) Rename: Documentation -> doc (or docs)?
	- Change the location for the translated documents?

2) What to do with the remaining 96 files under Documentation?

I tried my best to put the "lose" files at Documentation/
under either admin-guide or process. Yet, I skip several files
because I didn't know for sure what to do with them...

	- There are some stuff there that could probably be
	  discarded (for example: eisa.txt);
	- There are some stuff there that probably belong to
	  driver-api or to some other subsystem (like, for example
	  video-output.txt, with seems to be some GPU documentation);
	- There are some stuff there that contains both admin
	  documentation and driver documentation (like, for example
	  ntb.txt, with contains ABI documentation, module parameters,
	- There are files there with even code examples for userspace
	  tools, like: cpu-load.txt
	- On most cases, some work is needed for those files that
	  are still there...

3) long-term strategy for 00-INDEX:

On converted files, the index will be auto-generated, and the index.rst files
will contain the documents. Should we keep maintaining the 00-INDEX files in
long term? or should we do something else:
	move it to /README?
	remove it?
	put only directories there?

4) Should we add a generic Sphinx module to run scripts (e. g.) kernel-cmd?

	- If so, what would be the rules for using it?

My suggestion it to block it to run only scripts under an specific
directory (like Documentation/sphinx) and selected scripts under ./scripts
(like ./get-maintainers and ./kernel-doc). Scripts that will be run should
be submitted to kernel-doc ML and acked-by the documentation maintainer
or merged via documentation tree.

5) ABI parsing via script;
	- IMHO, this the onlg viable way of handling it;
	- Perhaps add part of the contents of ABI/README at the rst file;
	- ABI format: sort, sub-chapters, etc;
	- ABI files with a "header" text;
	- Should ABI be kept under docs, if not converted to ReST?
	- Should we use a new tag to allow descriptions in ReST format?

6) MAINTAINERS file
   - Should we add it to process documentation? IMHO, we should, at least a
     "short" version of it, with the name/location of the modules, the
      git tree and the ML for submissions.

7) PDF, LaTeX and Math extension

Can it be improved?

Cheers,
Mauro