Groups | Search | Server Info | Keyboard shortcuts | Login | Register

Groups > linux.debian.doc > #7882

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

Show all headers | View raw

Carlos Peralta <carlos9178028@gmail.com> writes:

> ​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.

It's good to think about the user of documentation before the structure


> ​Here is what I have in mind:
> ​1. Users Section
> This would be the starting point for anyone installing Debian.

Here we need to be careful - "anyone" installing debian includes

- people who have never used linux (only used windows/android/iphone/etc)
- people who have used other linux distributions (many sub-categories)
- people who have used debian, and just bought a new computer/are re-installing
- people who have used debian, and are setting up a server
- people using debootstrap or similar
- people testing the installation process
- probably others

differnet groups need different things. i think you only focused on the
first category.

> 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.

one question here is: should this be separate, or should the installer
make it so obvious this isnt needed


> ​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.

why advertise non-free software here?


> ​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.

this seems rather niche, especially given your section 1. And
"developers" is v broad

> ​3. Volunteers / Contributors Section
> A dedicated space to organize the community effort:

this doesnt sounds like documentation. i think you could maybe meant
this to be information about debian as a project? documentation cannot
realistically do all the things you list below

> ​A clear breakdown of the different areas that currently need help.

good luck identifying this!


> ​An explanation of what each area does and how to execute the tasks
> required.

this is a very mechanical framing

> ​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.

maybe start with: what learning do you want readers to take?

> ​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!

As well as the user, i would encourage you to think about what the
purpose and scope of any documentation is: there are definiely some
things that should be considered when writing all documentation
(audience, purpose, assumptions, etc), but a unified structure seems
unlikely: would you try and impose a unified sturcture on code?

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