Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.debian.doc > #7883

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

Show all headers | View raw

[Multipart message — attachments visible in raw view] - view raw

​Hi everyone,
​Thank you for the detailed feedback. You made some excellent points that
helped me see the broader picture of the project.
​differnet groups need different things. i think you only focused on the
first category.
​You are completely right. I was narrowly focusing on first-time Linux
users. After reflecting on your feedback, I realize that dividing the
documentation by "Experience Levels" or "User Pathways" might be a much
better approach than a monolithic structure. For example, having distinct
entry points for:
​First-time Linux users (coming from Windows/macOS).
​Users migrating from other distros.
​Advanced users setting up servers or using debootstrap.
​one question here is: should this be separate, or should the installer
make it so obvious this isnt needed
​Ideally, the installer should be entirely self-explanatory. However,
documentation serves as the essential safety net for edge cases or for
users who want to understand the "why" behind the process, rather than just
clicking "Next".
​why advertise non-free software here?
​My intention is absolutely not to advertise or promote non-free software
over free alternatives. However, from a newcomer's perspective, hardware
compatibility (like Wi-Fi cards or Nvidia GPUs) is often the biggest wall.
Providing clear, official guidance on how to enable non-free-firmware or
non-free components when strictly necessary prevents users from getting
frustrated and abandoning Debian simply because their hardware doesn't work
out of the box.
​this seems rather niche... this doesnt sounds like documentation.
​I concede both points. You are right that the Developer and Volunteer
sections fall more into project management and internal wiki domains rather
than standard system documentation. I will drop those ideas and focus
solely on the user onboarding experience for now.
​maybe start with: what learning do you want readers to take?
​The main goal is independence: giving users the exact knowledge they need
to manage their system confidently at their current experience level.
​Tomorrow I will be spending time reading through the current wiki and
official pages to get a better feel for the existing flow and see if I can
help with Spanish translations or fixing syntax errors I've noticed, rather
than trying to reorganize everything at once.
​Thanks again for guiding me in the right direction!
​Best regards,
​Carlos

El dom, 3 de may de 2026, 06:20, Richard Lewis <
richard.lewis.debian@googlemail.com> escribió:

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