From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id A5A7D4C84 for ; Fri, 17 Jun 2022 20:57:17 +0000 (UTC) Received: from localhost (unknown [IPv6:2601:281:8300:73::5f6]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ms.lwn.net (Postfix) with ESMTPSA id 9AD2E380; Fri, 17 Jun 2022 20:57:11 +0000 (UTC) DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 9AD2E380 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1655499431; bh=QHrwIn58SgXl8Bet1v2+WpPM77eMl/K5oLiuEM/QJYI=; h=From:To:Subject:Date:From; b=o2DZ88UA3mBD8QWmyxSsUoOyzZgCaihw4FaHxyh1E+YJnHM/AQgxeVmj8hvkQkNKe RzNXmDzN0XRPKPuqBdub0n4lQIIYZO1Wc9aW+i+naSRObD0rkvNxQXYXyGnX43XSWx oOb8qfjSO2cFa/qynDLwae/3Pe8nxokzXLyLCBqUxk5A7cILb77FHWlVxCicMQASvB dSxIROlT7UrwEl0hh88nVczHF7VOtAqxeKmSs8iSaXgPJ8c8205jEOnPCGt2O+DnKi DmSVSefZ7DulhMR/7ENjj/ianFH1e8TwFiCqwNMbiDMteGUY+lgDgFuczZ1tZoJzio lTx+m3gz6P0dQ== From: Jonathan Corbet To: ksummit-discuss@lists.linuxfoundation.org, ksummit@lists.linux.dev Subject: [TECH TOPIC] What kernel documentation could be Date: Fri, 17 Jun 2022 14:57:10 -0600 Message-ID: <87sfo3nh3t.fsf@meer.lwn.net> Precedence: bulk X-Mailing-List: ksummit@lists.linux.dev List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain The development community has put a lot of work into the kernel's documentation directory in recent years, with visible results. But the kernel's documentation still falls far short of the standard set by many other projects, and there is a great deal of "tribal knowledge" in our community that is not set down. I'd like to look at the successes and failures of the work so far, but intent to focus on a discussion of what our documentation should be and what we can do to get it there. Questions to discuss include: - Bringing an coherent overall structure to Documentation/ - Making it easier for developers to improve the documentation. - What we would like from Sphinx and what we can do to make it happen - Making the docs build system less ugly and more maintainable - Integrating rustdoc documentation jon From mboxrd@z Thu Jan 1 00:00:00 1970 From: Jonathan Corbet Date: Fri, 17 Jun 2022 14:57:10 -0600 Subject: [Ksummit-discuss] [TECH TOPIC] What kernel documentation could be Message-ID: <87sfo3nh3t.fsf@meer.lwn.net> Message-ID: <20220617205710.QALI-P3fei6--HyNgkD8H_Vy4lhy8DoJZ0NewhhNAEQ@z> The development community has put a lot of work into the kernel's documentation directory in recent years, with visible results. But the kernel's documentation still falls far short of the standard set by many other projects, and there is a great deal of "tribal knowledge" in our community that is not set down. I'd like to look at the successes and failures of the work so far, but intent to focus on a discussion of what our documentation should be and what we can do to get it there. Questions to discuss include: - Bringing an coherent overall structure to Documentation/ - Making it easier for developers to improve the documentation. - What we would like from Sphinx and what we can do to make it happen - Making the docs build system less ugly and more maintainable - Integrating rustdoc documentation jon