[Off-Topic] Help wanted: Writing a beginner's book to Debian

[Hallvor]

Hi all!


Having written a couple of books before, I will attempt to write a beginner's book to Debian. I firmly believe that a beginner's book could attract new users, and also that attracting new users would be beneficial to Debian in the long run.

A Debian beginner's book would hit a segment where there aren't really any tailored books, at least in Norwegian and possibly also in English.

I could do it alone, but a small team would be even better. That's why I'm reaching out to you for advice and/or help.

Specifically, I'm looking for general help (read: I am open for input from all) on these points:

* Feedback on the structure and content: Here is a basic outline (see below), but I'd love your thoughts on what topics are most crucial for beginners. If you are a beginner, I would love to hear from you.
* Recommendations for existing resources: I will try to look for the newest and best books, manuals and websites. What books, manuals or websites do you suggest?
* General suggestions: Any advice you have for making the book informative, engaging, and helpful would be greatly appreciated.


If you want to be a co-author, you should have one of the following qualifications. We should have people to fill all these roles:

* Someone with teaching experience or experience with technical assistance. The advice should be very easy and straight forward to follow.
* Someone highly skilled in Debian (preferably veteran member or DD) for quality control.
* Someone very proficient in written English to improve the language.
* Someone who could help make screenshots from the CLI and several desktop environments, because we all like screenshots

We also need someone with very little experience with Debian (for testing)


Timeline:

We all live busy lives, so I won't push for specific deadlines, but getting it ready for the first few months of Debian trixie would be nice. That should be in a little more than a year from now.


Here's a preliminary outline of the book:


Part 1: Introduction to Debian

History and Philosophy of Debian
Advantages of using Debian
Understanding Different Debian Releases (Stable, Testing, Unstable)
Desktop environments


Part 2: Getting Started with Debian

Downloading the installer image
Installation process (graphical and command-line)
Basic system configuration (keyboard, language, etc.)


Part 3: Essential Tools and Techniques

Understanding permissions
Navigating the file system with the terminal
Text editor (nano)
Package management with apt
User and group management and maintenance
Troubleshooting tips


Part 4: Resources and Community

Official Debian Documentation
Online forum
Contributing to Debian
Appendix


This is just a starting point, and I'm open to any suggestions you have for improvement.

Suggestions for resources and improvements to the general outline should be posted in this thread.

If you want to help, post in this thread or send me a PM.

Let's do this!

[Uptorn]

Consider producing examples of how to do the same things both in GUI and terminal form, to help drive home the point that desktop environments act as an intermediary between you and the system.

It might also be worth touching on hardware, maybe in the troubleshooting section.

[pbear]

Having attempted something of the sort three times, I've come to the conclusion what you have in mind can't be done.

There are several reasons. First, Linux is a branching options problem on steroids. There is no way to do a simple guide which captures even the most important options. Second, no one wants to read instructions. It's not our natural way to learn. We learn by sitting around a fire while someone demonstrates how to make an arrowhead and describes it verbally. There's a reason we still use teachers in school. Most Linux newbies want YouTube videos, not tutorials. Third, anything written about Linux has a short shelf life, as the OS has thousands of components, all of which are constantly changing.

If you're nonetheless keen to try, I suggest a slightly different approach. Rather than a manual, write a road map. Welcome to Linux. There are many ways to do this. I'm going to describe a good way to do your first installation. Later, when you understand how Linux works, you can plan a second installation tailored to your needs. For purposes of illustration, I'm going to assume you have (or will buy) a spare computer you can dedicate to Linux. It's possible to put Linux on a computer with Windows, but that's more complicated. Let's start with simple. Step One, ...

For what it's worth, I used to be a technical writer. Although relatively new here, I have something like 10,000 posts on Linux forums and have written several tutorials. Indeed, have three I'm working on now to post here.

[sunrat]

The forum's own Beginner's Guide is a good place to start.

[cds60601]

I for one, appreciate books (if indeed it's going to be in print).
The more there are, the better the coverage. No two books are the same and present (more often than not) differing perspectives on the same material.
I commend the attempt and will consider how I can contribute.

[trinidad]

I purchased the full OS boxed CD set for Jessie and it came with a decent installation manual which I referenced a time or two at first but then discovered the online documentation for Debian was more detailed. The same with Suse Enterprise though in that case the manual was very handy and the online documentation directed you to help sessions too quickly too many times even for simple answers. There is a niche for a decently detailed installation manual, basically something for people who only have access to one computer and want to install Debian... or for people who want to run a closed environment with no internet access. Perhaps, and I'm not being facetious, a moderately in depth, technically precise, and detailed operation manual for computing with a Debian OS not connected to the Internet... and then another separate one on Networking with Debian. The first would fill a very small niche, and the second would be unimportant once the Internet connection was successful. In the end... any good print documentation on Debian would be welcome. I wish you success.

TC

[pbear]

Speaking of resources already available, [HowTo] Install and configure Debian bookworm, written by Hallvor, of course.

[Hallvor]

First, Linux is a branching options problem on steroids. There is no way to do a simple guide which captures even the most important options.

Thank you for your input! It is important to be aware of pitfalls - appreciated. Please let me clarify that I don't want to enter a debate here, but this is for clarification.

I believe it is possible to focus on a step-by-step installation and very common use cases. Just the most basic fundamentals to get your system up and running and getting the most important understanding of the system, all illustrated with screenshots. This will assist them in getting started. They can later (or simultaneously) use other resources and explore more advanced features at their own pace.

Second, no one wants to read instructions. It's not our natural way to learn.

If that was the case, no one would purchase books about Linux - ever; they would all watch YouTube videos. The fact is that some people just prefer reading books over multimedia content. Books can be used as quick references, or people can read them on the bus when they don't have a computer at hand. I know that this isn't for everyone, but there is most certainly a segment of people who do.

Third, anything written about Linux has a short shelf life, as the OS has thousands of components, all of which are constantly changing.

Indeed, such a book will have a short shelf-life - a couple of years and it's outdated. However, the changes are generally small and incremental. Fortunately we don't see a total rewrite of Debian every two years. I am certain that I could rewrite a book like this for a new version of Debian in a few days. Taking new screenshots would probably be at least half the job.

Rather than a manual, write a road map. Welcome to Linux. There are many ways to do this. I'm going to describe a good way to do your first installation. Later, when you understand how Linux works, you can plan a second installation tailored to your needs. For purposes of illustration, I'm going to assume you have (or will buy) a spare computer you can dedicate to Linux. It's possible to put Linux on a computer with Windows, but that's more complicated. Let's start with simple. Step One, ...

This is more or less what I had in mind for part 2 in the preliminary outline above - everything should be easy and step by step. I am a teacher, and you are a technical writer. That sounds like a great match. Let me know if you want on board.

[Hallvor]

I for one, appreciate books (if indeed it's going to be in print).
The more there are, the better the coverage. No two books are the same and present (more often than not) differing perspectives on the same material.
I commend the attempt and will consider how I can contribute.

Thank you for your interest! Let me know if you want on board.

[bbbhltz]

I like that you've limited your scope. I would love to be able to help out in any way. I'm a English and Business professor. How have you planned on preparing the document? LaTeX, Markdown?

[Hetzer]

Second, no one wants to read instructions. It's not our natural way to learn. We learn by sitting around a fire while someone demonstrates how to make an arrowhead and describes it verbally. There's a reason we still use teachers in school. Most Linux newbies want YouTube videos, not tutorials.

I'd not agree that no one wants to read instructions, or at least I do want to do so. It's quick resource of information free of off-topic babble (especially that sponsorship one) and not dependant on problematic service
Even better are the guides. These fulfill manuals with explanations, examples and tutorials (with troubleshooting). Good example of well-done guide is the FreeBSD Handbook

Third, anything written about Linux has a short shelf life, as the OS has thousands of components, all of which are constantly changing.

Indeed, such a book will have a short shelf-life - a couple of years and it's outdated. However, the changes are generally small and incremental. Fortunately we don't see a total rewrite of Debian every two years. I am certain that I could rewrite a book like this for a new version of Debian in a few days. Taking new screenshots would probably be at least half the job.

However some things in Linux don't change at all, like "Wild West" package-centric approach (in case of Linux in general) or "stability over bleeding edge" mentality of Debian
I think personally that it's best to write it as release-agnostic and possible and focus mainly on Debian philosophy and it's way to do things right
Such writables should then last longer than to next major release. And one would bring out more out of it as he/she would be told how to do things and how to get help instead of just knowing specific ways without being aware how to adjust it for other scenarios
Parts like system installation can't be of course done release-agnostic and must be therefore updated as time goes by, however in the end my approach would still result, I believe, in better book that would be easier to maintain (because of being "release-agnostic")

[Uptorn]

It is coincidental that this topic should arise just as I am considering buying a Debian book. I had lately taken an interest to historic Debian and wanted to dive into some of the archived Debian releases (from before I'd started using Linux). And a book from that period would be helpful as I have no idea how to use dselect or what to do with the installation images there were broken up across multiple disks unlike today's netinst.

There has been no shortage of books written about Debian.

Years ago, I would have agreed that watching Youtube videos would be sufficient. But the more I learn about Linux, the more apparent it becomes that these Youtube gurus often supply incomplete information or even get things wrong (because they themselves are just rehashing what they read from some blog post, most likely). And, increasingly, things are just getting harder to find on Youtube, and on search engines generally.

So to throw in a vote of confidence for physical books, I'm proud to have a dozen computer and programming books right here on the shelf beside me. And looking to expand the collection. The history of Debian, on its own, would even make for an interesting book. Did you know that the Debian project nearly went bust after the mailing list generously hosted by Bruce Perens was taken down when he left the project?

[Hallvor]

I like that you've limited your scope. I would love to be able to help out in any way. I'm a English and Business professor. How have you planned on preparing the document? LaTeX, Markdown?

Thanks! PM sent.

[Augie77]

What really helped me, or at least my way of learning, were the SAMS books. They were a big step above the Something for Dummies style of books. The SAMS books hit the right spot for teaching a new person just what they needed to know to be functional, and confidant after a few weeks. An example would be in Terminal have simple examples and parameters of a command the beginner will likely use, not some command with obscure parameters that only an IT admin would use.

Don't be wordy! Most books or manuals are an extension of the writers ego and command of words. They will take 3 paragraphs to explain what could have been done in 1 paragraph. Don't use real life world examples of your own personal experience. No reader cares how you mucked up an install 11 years ago. When teaching a terminal command, don't bother to give the history of the command. Wasted reading time for the beginner, most simply do not care about the evolution of some command. Simple instructions is what beginners need...not a tome.

Understand that the vast number of beginners have no desire to be like you, or any highly experienced Linux admin. Most simply want a Windows replacement and could give a hoot less about the inner workings of the EXT4 file system...or its history. I have looked at a lot of Linux how-to books, all failed simply because they were too wordy and the author thought he was writing a course for college. It is often hard for intelligent and well versed authors to comprehend that most of the world could care less about the deep, inner workings of Linux.

Written from the perspective of a 68 year old man that trained people in mainframe and software maintenance, as well as wrote a few training guides in the military many years ago.

edit: change users to writers, second paragraph, second sentence.

[Hallvor]

Thanks, Augie77! That is great advice - I'll keep that in mind.

[Trihexagonal]

I struggled learning to use FreeBSD, becoming a beta tester for PC-BSD in 2005,thinking the FreeBSD Handbook was not applicable, and taught myself to use ports.

After having moved to vanilla FreeBSD, in 2017 I wrote a Beginners Tutorial on Building a FreeBSD Desktop from Scratch using ports for 3rd party applications with a target audience of a Windows user that had never used the command line so the blood, sweat and tear shed by me as a n00b need not be shed twice.

I had previous experience writing Task Analysts for mundane things like making a peanut butter and jelly sandwich as Home Manager of Group Homes for Developmentally Disabled Individuals that spelled out every step of the process in excruciating detail, down to which was the dominate hand.

Not for the clients. They couldn't make a pbj much less read a Task Analysis. For staff so they would teach the skill in a consistent manner and this is the format I used writing the Tutorial.

It did very well, with over 100,000 views of it posted in the FreeBSD forums and I hosted it on my website and promoted it on my own dime without any mention of it existing from the FreeBSD Project or Foundation, though it was featured twice in freebsdnews.com and help the top 5 spots in a Google Search till I took it offline in 2021.

This after informing Admin the FreeBSD forums no longer reflected my values and if they would be so kind as to delete that Tutorial and another I wrote I would disappear with them. Instead they chose to delete mtyaccount and name as Author of the Tutorials. That constitutes Copyright Infringement, Google agreed and filed a notice of DMCA Copyright Complaint on both counts:

https://lumendatabase.org/notices/27708765

Do I think Debian Administrative Staff would do such a thing? No I do not, but I have been surprised before anf this just a heads-up on the pitfalls of Authorship.. Did it do any good or have any impact on the situation? No it did not, and things unchanged since 2021.

With the exception of ab unexpected rebound from a rare, progressive brain disease called Hepatic Encephalopathy they were aware of that was robbing me of all my skills and abilities to the point I had almost lost my ability to write completely at that point. I am much better now, thank you.

I put my site back up a couple days ago, will be posting all relevant documentation, the legal argument showing it is covered under Copyright Law and am now in the process of securing a lawyer that works with Copyright Law to file suit against the FreeBSD Project and Foundation in US Federal Court.

How Copyright Infringement, BSD License and GNU mesh together I am still trying to figure out. But a FreeBSD CoC that considers virtual hugs offensive and turns a blind eye to Copyright Infringement by FreeBSD Admin something I will provide documentation of on my site.

I can't help you with your writing but you can see what a Task Analysis looks like on my site. Good luck.

https://trihexagonal.org/

[Enigma83]

I really don't see the point, there are enough Debian getting started guides out there, writing yet another book seems redundant and a waste of time.

There is also a Debian Reference/handbook that you can find in a quick Web search, hosted right on Debian's official website, of all places. It's very thorough, available in multiple languages, and in multiple formats for both online reading or offline. If someone is too ignorant or dumb to get the idea to search out and find said guide, then they have no business using Debian or Linux, such a person should just use Windows. These people are just lazy, period. Linux generally isn't hard to learn if you're committed, but it does require more dedication than mainstream Windows, so this dedication should be matched with a willingness to search for the info that will aid in learning it.

There ate also manpages built into the distro for most programs, which are accessible even offline on a computer that has no internet connection. These aren't Debian guides/tutorials/books, per se, but they provide enough info to get you started.

[Trihexagonal]

If someone is too ignorant or dumb to get the idea to search out and find said guide, then they have no business using Debian or Linux, such a person should just use Windows. These people are just lazy, period.

You'll never bring in new users to Debian or see the fabled Year of the Linux Desktop with that elitist attitude.
Exactly the opposite and there is always somebody more 1337 than joo.

[Enigma83]

If someone is too ignorant or dumb to get the idea to search out and find said guide, then they have no business using Debian or Linux, such a person should just use Windows. These people are just lazy, period.

You'll never bring in new users to Debian or see the fabled Year of the Linux Desktop with that elitist attitude.
Exactly the opposite and there is always somebody more 1337 than joo.

It's not about being elitist/1337, as I said, Linux isn't hard to learn. In the past Linux has gotten a bad rep for being for geeks/nerds only. It's harder than Windows for many, but it's not rocket science. I just feel like people should put in the effort to learn it on their own. Seeking out a guide isn't hard to do, and if one is really motivated to find the info they need, then it stands to reason that they would do exactly that. And they would likely happen upon the Debian Reference I already mentioned, if they were looking for info specific to this distro.

It's also already been said that a book would probably be out of date in a few yrs, this often is the case with books that fall in the manual/how to/reference category. Yet another reason to not write yet another book. It's not like a novel, say, The Hobbit, which is entirely fiction and will still be read centuries from now.

[Onsemeliot]

I have been using Debian since 2008 and I still struggle with tasks that I haven't done yet. Maybe I am not bright enough, but when I for example tried finding a guide that allows me to create my own Debian package for a free game I am involved in I was just overwhelmed by several thousands of pages that all start with mentioning what other similarly extensive books I should read, before even starting with the one I found. I craved for an easy guide to get going for the first steps but could only find vast exhaustive monuments. (While at the same time I was told that it is supposed to be very easy. Well, maybe for someone who already knows enough about it.) And I also have the impression that the terminal manuals are mostly useful to advanced users who already know enough for at least basic usage and just need more detail when they want to do more specific things. They aren't very helpful if you are new to something and do not even know how the software or command you are searching for is called or what you should use for which tasks in which circumstances.

All to say: Easy steps are certainly still very welcome from my viewpoint. So I too applaud your aim for creating an easy entry point but at the same time I fear I can't offer to contribute anything meaningful since I already struggle to do most of what I want to do.