Tag / Documentation

  • October 28, 2016 - Mauro Carvalho Chehab

    Improving Linux Kernel Development Process Documentation

    This article will cover how the Linux kernel community handled the conversion of documentation related to the kernel development process; it’s part of a series on improvements being made to Linux kernel documentation. Introduction It’s not an easy task to properly describe the Linux development process. The kernel community moves at a very fast pace and produces about 6 versions per year. Thousands of people, distributed worldwide, contribute to this collective work; the development process is a live being that constantly adjusts to what best fits the people involved in the process. Additionally, since kernel development is managed per subsystems, each maintainer has their own criteria for what works best for the subsystem they take care of. To address this, the documentation provides a common ground for understanding the best practices all kernel developers should follow. The Documentation/Development-Process Book There are several files inside the kernel that describes the development […]

    Read More
  • October 20, 2016 - Mauro Carvalho Chehab

    Creating a Linux Kernel User’s Manual

    This article is part of a series on improvements being made to Linux kernel documentation. This article will discuss the efforts that are underway for kernel 4.10 to produce a Linux User’s Manual that groups the existing user-focused documents. What Defines a Linux Kernel User? It’s not an easy task to identify the documents that contain useful information for Linux kernel users because there are a large number of documentation files inside the kernel tree and these documents are mixed with development documents. Furthermore, who exactly are the Linux kernel tree users? Are they the end users who run various Linux distributions, the distribution packagers that package the kernel tree, or the advanced Linux users and system administrators that opt to compile the kernel themselves? In other words, depending on what definition of users we use, the contents of a Linux user’s manual varies. For the scope of this work, […]

    Read More
  • This article is a part of a series that covers improvements that are being made to the Linux Kernel documentation; this article will begin to explain how we handled the conversion of the Linux Media subsystem documentation. The Linux Media Subsystem The Linux Media subsystem is actually a set of subsystems; each subsystem has its own particularities: Video4Linux –  API and core provide functions for video stream capture and output. It also provides support for video codecs, analog TV, AM/FM radio receivers and transmitters and for software digital radio (SDR) receivers and transmitters. Linux DVB – provides support for digital TV. Despite its name, it supports worldwide standards, including DVB, ATSC, ISDB, and CDDB, as well remote controllers and infra-red devices. Media Controller – provides pipeline control and reconfiguration inside the hardware. HDMI CEC – provides support for the HDMI Consumers Electronic Control (CEC): a system to pass remote controller […]

    Read More
  • This article is the first in a series on improvements to Linux Kernel documentation. The Linux Kernel has one of the biggest communities in the open source world; the numbers are impressive: over 4,000 contributors per year, resulting in about 8 changes per hour. That results in 4,600 lines of code added every day and a major release every 9-10 weeks. With these impressive numbers, it’s impossible for a traditional printed book to follow the changes because by the time the book is finally written, reviewed and published, a lot of changes have already merged upstream. So, the best way to maintain updated documentation is to keep it close to the source code. This way, when some changes happen, the developer that wrote such changes can also update the corresponding documents. That works great in theory, but it is not as effective as one might think. The Old Methods of […]

    Read More
  • Open Source Wrap Up: August 1 – 7, 2015 18F Releases Style Guide for Open Source Project Documentation 18F is a US Government organization inside the General Services Administration that helps federal agencies adopt modern approaches to managing and delivering digital services. They’ve worked on initiatives with the Department of Labor, Social Security Administration, Department of Defense, and more to help them adopt modern technologies. A big part of the work 18F does is rooted in open source, and the organization has released a style guide for open source projects. The guide includes information to improve a project’s success on places like GitHub. It covers things like naming the project, writing repo descriptions, writing good README files, and best practices for using a wiki. The guide is full of great information about how to best help potential contributors through proper documentation. Check out the Open Source Style Guide here. US House […]

    Read More