Groups | Search | Server Info | Login | Register

Groups > linux.debian.doc > #7880

Re: An idea for organizing the documentation: A 3-section approach

Show all headers | View raw

Hi Carlos,

thanks for your interest & ideas!  If people in Debian would start writing
documentation from scratch, we'd probably follow a setup similar to the one you
propose.  However, as you said we already have quite a lot of documentation;
the challenge now would be to try to gradually move and/or adapt existing
documentation to your proposed scheme.

Also: As you can see at https://www.debian.org/doc/#manuals , there is a
section for users and one for developers.  If you have small specific
suggestions, please do provide some patch / MR for
https://salsa.debian.org/webmaster-team/webwml/-/tree/master/english/doc?ref_type=heads
.  In general, I believe for new contributors, starting with small changes /
suggestions is the best way to get acquinted with the work.

Thanks for your suggestion; you are right there is room for improvement :)

Bye,

Joost


Le Sat, May 02, 2026 at 10:24:55PM -0500, Carlos Peralta a écrit :
> ​Hi everyone,
> ​As a new user getting involved in the project, I have been thinking about
> how the documentation is presented. I would like to share an idea for
> structuring it into three main sections to make it more intuitive,
> especially for newcomers.
> ​Here is what I have in mind:
> ​1. Users Section
> This would be the starting point for anyone installing Debian. It could
> cover:
> ​Installation: Step-by-step guides for both GUI and CLI (Command Line
> Interface). A key addition would be explaining exactly what each command
> does during the CLI installation.
> ​System Management: Basic commands for updating the system,
> downloading/installing software, and how to properly add proprietary
> (non-free) software.
> ​Terminal Basics: A brief guide on how to navigate the terminal.
> ​2. Developers Section
> This section would dive into the technical side of the OS:
> ​Deep dive documentation into the Debian codebase.
> ​A comprehensive guide on how to create a custom distribution based on
> Debian.
> ​3. Volunteers / Contributors Section
> A dedicated space to organize the community effort:
> ​A clear breakdown of the different areas that currently need help.
> ​An explanation of what each area does and how to execute the tasks
> required.
> ​Clear instructions or a sign-up process for those who want to support a
> specific team.
> ​I understand Debian already has a massive amount of documentation, but I
> thought a unified structure like this could make the learning curve much
> smoother.
> ​I would love to hear your thoughts on this approach or if there is already
> an ongoing effort similar to this that I can help with!
> ​Best regards,
> ​Carlos

Back to linux.debian.doc | Previous | Next — Previous in thread | Next in thread | Find similar

Thread

An idea for organizing the documentation: A 3-section approach Carlos Peralta <carlos9178028@gmail.com> - 2026-05-03 05:30 +0200
  Re: An idea for organizing the documentation: A 3-section approach Mechtilde Stehmann <mechtilde@debian.org> - 2026-05-03 08:50 +0200
  Re: An idea for organizing the documentation: A 3-section approach Joost van Baal-Ilić <joostvb-debian@mdcc.cx> - 2026-05-03 09:50 +0200
  Re: An idea for organizing the documentation: A 3-section approach Richard Lewis <richard.lewis.debian@googlemail.com> - 2026-05-03 13:30 +0200
    Re: An idea for organizing the documentation: A 3-section approach Carlos Peralta <carlos9178028@gmail.com> - 2026-05-03 22:30 +0200

csiph-web