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

--000000000000e2d1b60650ef9426
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

=E2=80=8BHi everyone,
=E2=80=8BThank you for the detailed feedback. You made some excellent point=
s that
helped me see the broader picture of the project.
=E2=80=8Bdiffernet groups need different things. i think you only focused o=
n the
first category.
=E2=80=8BYou are completely right. I was narrowly focusing on first-time Li=
nux
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:
=E2=80=8BFirst-time Linux users (coming from Windows/macOS).
=E2=80=8BUsers migrating from other distros.
=E2=80=8BAdvanced users setting up servers or using debootstrap.
=E2=80=8Bone question here is: should this be separate, or should the insta=
ller
make it so obvious this isnt needed
=E2=80=8BIdeally, the installer should be entirely self-explanatory. Howeve=
r,
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".
=E2=80=8Bwhy advertise non-free software here?
=E2=80=8BMy intention is absolutely not to advertise or promote non-free so=
ftware
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.
=E2=80=8Bthis seems rather niche... this doesnt sounds like documentation.
=E2=80=8BI concede both points. You are right that the Developer and Volunt=
eer
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.
=E2=80=8Bmaybe start with: what learning do you want readers to take?
=E2=80=8BThe main goal is independence: giving users the exact knowledge th=
ey need
to manage their system confidently at their current experience level.
=E2=80=8BTomorrow 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.
=E2=80=8BThanks again for guiding me in the right direction!
=E2=80=8BBest regards,
=E2=80=8BCarlos

El dom, 3 de may de 2026, 06:20, Richard Lewis <
[email protected]> escribi=C3=B3:

> Carlos Peralta <[email protected]> writes:
>
> > =E2=80=8BHi everyone,
> > =E2=80=8BAs a new user getting involved in the project, I have been thi=
nking
> 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
>
>
> > =E2=80=8BHere is what I have in mind:
> > =E2=80=8B1. 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:
> > =E2=80=8BInstallation: Step-by-step guides for both GUI and CLI (Comman=
d Line
> > Interface). A key addition would be explaining exactly what each comman=
d
> > does during the CLI installation.
>
> one question here is: should this be separate, or should the installer
> make it so obvious this isnt needed
>
>
> > =E2=80=8BSystem Management: Basic commands for updating the system,
> > downloading/installing software, and how to properly add proprietary
> > (non-free) software.
> > =E2=80=8BTerminal Basics: A brief guide on how to navigate the terminal=
.
>
> why advertise non-free software here?
>
>
> > =E2=80=8B2. Developers Section
> > This section would dive into the technical side of the OS:
> > =E2=80=8BDeep dive documentation into the Debian codebase.
> > =E2=80=8BA comprehensive guide on how to create a custom distribution b=
ased on
> > Debian.
>
> this seems rather niche, especially given your section 1. And
> "developers" is v broad
>
> > =E2=80=8B3. 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
>
> > =E2=80=8BA clear breakdown of the different areas that currently need h=
elp.
>
> good luck identifying this!
>
>
> > =E2=80=8BAn explanation of what each area does and how to execute the t=
asks
> > required.
>
> this is a very mechanical framing
>
> > =E2=80=8BClear instructions or a sign-up process for those who want to =
support a
> > specific team.
> > =E2=80=8BI understand Debian already has a massive amount of documentat=
ion, but I
> > thought a unified structure like this could make the learning curve muc=
h
> > smoother.
>
> maybe start with: what learning do you want readers to take?
>
> > =E2=80=8BI would love to hear your thoughts on this approach or if ther=
e 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?
>
>

--000000000000e2d1b60650ef9426
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"auto">=E2=80=8BHi everyone,<div dir=3D"auto">=E2=80=8BThank you=
 for the detailed feedback. You made some excellent points that helped me s=
ee the broader picture of the project.</div><div dir=3D"auto">=E2=80=8Bdiff=
ernet groups need different things. i think you only focused on the first c=
ategory.</div><div dir=3D"auto">=E2=80=8BYou are completely right. I was na=
rrowly focusing on first-time Linux users. After reflecting on your feedbac=
k, I realize that dividing the documentation by &quot;Experience Levels&quo=
t; or &quot;User Pathways&quot; might be a much better approach than a mono=
lithic structure. For example, having distinct entry points for:</div><div =
dir=3D"auto">=E2=80=8BFirst-time Linux users (coming from Windows/macOS).</=
div><div dir=3D"auto">=E2=80=8BUsers migrating from other distros.</div><di=
v dir=3D"auto">=E2=80=8BAdvanced users setting up servers or using debootst=
rap.</div><div dir=3D"auto">=E2=80=8Bone question here is: should this be s=
eparate, or should the installer make it so obvious this isnt needed</div><=
div dir=3D"auto">=E2=80=8BIdeally, the installer should be entirely self-ex=
planatory. However, documentation serves as the essential safety net for ed=
ge cases or for users who want to understand the &quot;why&quot; behind the=
 process, rather than just clicking &quot;Next&quot;.</div><div dir=3D"auto=
">=E2=80=8Bwhy advertise non-free software here?</div><div dir=3D"auto">=E2=
=80=8BMy intention is absolutely not to advertise or promote non-free softw=
are over free alternatives. However, from a newcomer&#39;s perspective, har=
dware 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&#39;t=
 work out of the box.</div><div dir=3D"auto">=E2=80=8Bthis seems rather nic=
he... this doesnt sounds like documentation.</div><div dir=3D"auto">=E2=80=
=8BI concede both points. You are right that the Developer and Volunteer se=
ctions fall more into project management and internal wiki domains rather t=
han standard system documentation. I will drop those ideas and focus solely=
 on the user onboarding experience for now.</div><div dir=3D"auto">=E2=80=
=8Bmaybe start with: what learning do you want readers to take?</div><div d=
ir=3D"auto">=E2=80=8BThe main goal is independence: giving users the exact =
knowledge they need to manage their system confidently at their current exp=
erience level.</div><div dir=3D"auto">=E2=80=8BTomorrow I will be spending =
time reading through the current wiki and official pages to get a better fe=
el for the existing flow and see if I can help with Spanish translations or=
 fixing syntax errors I&#39;ve noticed, rather than trying to reorganize ev=
erything at once.</div><div dir=3D"auto">=E2=80=8BThanks again for guiding =
me in the right direction!</div><div dir=3D"auto">=E2=80=8BBest regards,</d=
iv><div dir=3D"auto">=E2=80=8BCarlos</div></div><br><div class=3D"gmail_quo=
te gmail_quote_container"><div dir=3D"ltr" class=3D"gmail_attr">El dom, 3 d=
e may de 2026, 06:20, Richard Lewis &lt;<a href=3D"mailto:richard.lewis.deb=
[email protected]">[email protected]</a>&gt; escribi=C3=
=B3:<br></div><blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;=
border-left:1px #ccc solid;padding-left:1ex">Carlos Peralta &lt;<a href=3D"=
mailto:[email protected]" target=3D"_blank" rel=3D"noreferrer">carlos=
[email protected]</a>&gt; writes:<br>
<br>
&gt; =E2=80=8BHi everyone,<br>
&gt; =E2=80=8BAs a new user getting involved in the project, I have been th=
inking about<br>
&gt; how the documentation is presented. I would like to share an idea for<=
br>
&gt; structuring it into three main sections to make it more intuitive,<br>
&gt; especially for newcomers.<br>
<br>
It&#39;s good to think about the user of documentation before the structure=
<br>
<br>
<br>
&gt; =E2=80=8BHere is what I have in mind:<br>
&gt; =E2=80=8B1. Users Section<br>
&gt; This would be the starting point for anyone installing Debian.<br>
<br>
Here we need to be careful - &quot;anyone&quot; installing debian includes<=
br>
<br>
- people who have never used linux (only used windows/android/iphone/etc)<b=
r>
- people who have used other linux distributions (many sub-categories)<br>
- people who have used debian, and just bought a new computer/are re-instal=
ling<br>
- people who have used debian, and are setting up a server<br>
- people using debootstrap or similar<br>
- people testing the installation process<br>
- probably others<br>
<br>
differnet groups need different things. i think you only focused on the<br>
first category.<br>
<br>
&gt; It could<br>
&gt; cover:<br>
&gt; =E2=80=8BInstallation: Step-by-step guides for both GUI and CLI (Comma=
nd Line<br>
&gt; Interface). A key addition would be explaining exactly what each comma=
nd<br>
&gt; does during the CLI installation.<br>
<br>
one question here is: should this be separate, or should the installer<br>
make it so obvious this isnt needed<br>
<br>
<br>
&gt; =E2=80=8BSystem Management: Basic commands for updating the system,<br=
>
&gt; downloading/installing software, and how to properly add proprietary<b=
r>
&gt; (non-free) software.<br>
&gt; =E2=80=8BTerminal Basics: A brief guide on how to navigate the termina=
l.<br>
<br>
why advertise non-free software here?<br>
<br>
<br>
&gt; =E2=80=8B2. Developers Section<br>
&gt; This section would dive into the technical side of the OS:<br>
&gt; =E2=80=8BDeep dive documentation into the Debian codebase.<br>
&gt; =E2=80=8BA comprehensive guide on how to create a custom distribution =
based on<br>
&gt; Debian.<br>
<br>
this seems rather niche, especially given your section 1. And<br>
&quot;developers&quot; is v broad<br>
<br>
&gt; =E2=80=8B3. Volunteers / Contributors Section<br>
&gt; A dedicated space to organize the community effort:<br>
<br>
this doesnt sounds like documentation. i think you could maybe meant<br>
this to be information about debian as a project? documentation cannot<br>
realistically do all the things you list below<br>
<br>
&gt; =E2=80=8BA clear breakdown of the different areas that currently need =
help.<br>
<br>
good luck identifying this!<br>
<br>
<br>
&gt; =E2=80=8BAn explanation of what each area does and how to execute the =
tasks<br>
&gt; required.<br>
<br>
this is a very mechanical framing<br>
<br>
&gt; =E2=80=8BClear instructions or a sign-up process for those who want to=
 support a<br>
&gt; specific team.<br>
&gt; =E2=80=8BI understand Debian already has a massive amount of documenta=
tion, but I<br>
&gt; thought a unified structure like this could make the learning curve mu=
ch<br>
&gt; smoother.<br>
<br>
maybe start with: what learning do you want readers to take?<br>
<br>
&gt; =E2=80=8BI would love to hear your thoughts on this approach or if the=
re is already<br>
&gt; an ongoing effort similar to this that I can help with!<br>
<br>
As well as the user, i would encourage you to think about what the<br>
purpose and scope of any documentation is: there are definiely some<br>
things that should be considered when writing all documentation<br>
(audience, purpose, assumptions, etc), but a unified structure seems<br>
unlikely: would you try and impose a unified sturcture on code?<br>
<br>
</blockquote></div>

--000000000000e2d1b60650ef9426--