Carlos Peralta <[email protected]> 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?
