OSDev.org

I've considered doing this for a while, but up until recently I haven't had the energy to do it.

In my opinion - and the opinion of several other developers I've spoken to - the Bare Bones tutorials are confused and sometimes misleading for beginners. There is a huge amount of inconsistency and redundancy throughout the tutorials, and many areas of the tutorials encourage bad practices (without the necessary explanation that these things are bad practice). This is a problem not just for those following them, but also for the community. Tutorials that don't explain content well only encourage beginners to flood the forums and IRC with questions that shouldn't really need to arise in the first place.

I'm willing to put in the effort to do part of it, but I'd like to hear from the community on what you think of the tutorials and how they could be improved first.

For reference, I've written an almost-complete new version of Bare Bones that you can take a look at here: http://wiki.osdev.org/User:Zesterer/Bare_Bones

Hi,

zesterer wrote:I'm willing to put in the effort to do part of it, but I'd like to hear from the community on what you think of the tutorials and how they could be improved first.

If you provide example code (especially example code that can be compiled), then you end up with people that don't even think about what they actually want and only create a "cut & paste tutorial clone OS". If you make the example code simple then it only teaches "too simple to be actually useful in practice" and you end up with people that aren't even aware of how much their own project is lacking. If you don't make the example code simple then it becomes too complex for beginners to learn from.

My opinion is that a good tutorial should mostly consist of choices and descriptions of the advantages/disadvantages of those choices, and some advice and/or lists of things that might (or might not) be taken into account, and links to relevant pages of the wiki (for things like how to configure PIC chips, set up a GDT, etc), with no actual code in the tutorial at all. Essentially; in my opinion a good tutorial would force people to think about how they want to design their OS (instead of feeding them a shrink-wrapped design) and force people to learn how to implement their OS (instead of "cut & paste" without gaining any useful experience).


Cheers,

Brendan

Brendan wrote:My opinion is that a good tutorial should mostly consist of choices and descriptions of the advantages/disadvantages of those choices, and some advice and/or lists of things that might (or might not) be taken into account, and links to relevant pages of the wiki (for things like how to configure PIC chips, set up a GDT, etc), with no actual code in the tutorial at all. Essentially; in my opinion a good tutorial would force people to think about how they want to design their OS (instead of feeding them a shrink-wrapped design) and force people to learn how to implement their OS (instead of "cut & paste" without gaining any useful experience).

I understand where you're coming from. I don't intend to make a cut-and-paste tutorial, but I think that for the BareBones tutorials specifically there should be example code that explains to the letter how to get a minimal kernel up and running. This is for the same reason that when debugging, it's often useful to revert to a minimal case of the problem. If you remove the cruft entirely and make sure that the thing actually compiles, then you'll have far fewer newcomers asking questions about BareBones and the specifics of how a kernal should be compiled and linked. Rather than having a huge barrier to entry, it's probably better to lower the barrier to entry and then gradually increase the difficulty curve as developers become used to kernel development.

Beyond BareBones, I agree that anything more than simple code snippets are probably counter-productive. Any tutorials beyond BareBones I'd write would likely be more wordy.

Thanks for the suggestions.

I have to agree 100% with Brendan that tutorials in general, and particularly those that provide workable code, do more harm than good. As a couple of current threads demonstrate, we just end up with people saying they can't be bothered to read documentation, or don't understand it, and demanding example code. Otherwise they ask people to debug their Frankenstein code for them.

I'm certainly not defending the current bare bones tutorials - their only merit, to my mind,, is that they demonstrate how to use grub (and perhaps save us from yet another "I've written a bootloader"). So I would say the answer is less code and more general principles. If people haven't reached the stage where they can create code from general pointers and links to decent documentation they aren't up to OS development.

Anyone who states they can't be bothered to read the Intel or AMD manuals should be banned from the forums.

I am strongly in favor of providing both a working build system and working code to go with it. Anything less is pointless elitism.

By all means, explain the choices and simplifications you're making and point to places to learn more, but withholding basic information as a way to keep out people you don't want to deal with is ridiculous. Manage that problem with forum rules and a good community.

I don't see major issue with the current Barebone tutorials (eg. rpi one is working fine).

IMO the barebone tutorial is what get you started, and it's especially useful when you switch to a new architecture. It should go through(or via x-ref) a basic description of boot sequence(uboot/BIOS/UEFI), some basic code to boot and print a hello world, and a test/debugger environment.

We don't need to do anything more than hello world, by definition that's not barebone, it's another specific topic. We can still point to other suggested topics in the footer references.

Rusky wrote:Anything less is pointless elitism.

What you call "pointless elitism" is what I call "encouraging people to think for themselves" - they are just different educational philosophies.

You're right from your side and I'm right from mine.

iansjack wrote:tutorials in general ... do more harm than good.

This is not right from any reasonable perspective.

Tutorials do much more than just give people ideas (or code) to blindly copy. They trace a path through an unfamiliar space so people can have a foundation to start "thinking for themselves" from.

Building that foundation the way you and Brendan propose may work fine for some people, but it does involve digging up practical details about tools and platforms that are, without a good tutorial, scattered to the winds. Those details are like breathing for someone who has been doing this for a while, but a beginner hardly even knows what to look for. It's easy to forget that from the perspective of experience.

In your opinion.

I take the point of view that we are not teaching elementary C or assembler programming here, but are helping people who are proficient in those fields to get into operating system development. (I may be wrong in that opinion, but that's how I see this site as being most useful.)

Such people don't need step-by-step instructions that they can slavishly copy; they need the concepts specific to os development explained. The problem with tutorials (in my opinion - and let us not forget that this is all a matter of opinion) is that they encourage people who don't know the basics to cut-and-paste code and think that they know what they are doing. Then we get the inevitable "Why doesn't my (hah) code work" or "Where do I go now".

So I'm afraid that, in my opinion, you are being just a tad arrogant in asserting that my point of view is wrong "from any reasonable perspective". Wrong, in your opinion, perhaps; but that's just because, in my opinion, you don't understand the process of education. Your perspective is not reasonable. State your point of view by all means, and I will state mine, but please don't thoughtlessly assert that I must be incorrect.

"Give a man a fish and you feed him for a day; teach a man to fish and you feed him for life" (although nowadays that should read "until fish stocks are depleted").

Let's try to teach people to feed themselves rather than force-feeding them what is often junk food.

People who will potentially "succeed" in operating system development learn all the things thoroughly even if they start with "too good" tutorials. Making it hard to start means that less people start operating system development to begin with. Also, a lot of people may get useful experience from these tutorials even if they notice that serious operating system development is not their thing. Making "too good" tutorials keeps the absolute number of "successful developers" equal or above if compared to the opposite scenario. However, there will be more "casual developers" and for many people here that is the problem.

Rusky has a good point.

iansjack wrote:I take the point of view that we are not teaching elementary C or assembler programming here, but are helping people who are proficient in those fields to get into operating system development.

Fundamentally you are right but in practice assembler programming requires some reason (e.g. OSDev) to be relevant in a modern era of computing. The real pressure testing is when things are actually tried out in a real context and it is really hard/uninteresting to be fully prepared for this. Most of the time it sounds that our minimum knowledge requirements would be perfectly valid for people who have already made their first operating system and are starting the more serious attempt.

note he said C or assembler... not C and assembler...

there is no need to know assembler to write an OS, you need very little, and you don't need to know any to start (in fact, if you know C fairly well, you already know enough ASM to write an OS -- even if you think you don't know any ASM at all)



in my opinion, I wouldn't bother rewriting the existing tutorials, rather I would prefer to create a new starter tutorial to complement the current one (and make this new one prominent on the wiki, deprecating (but not removing) the old one) -- and this new tutorial should be UEFI only, with no mention of legacy BIOS loading (or grub -- which is pretty much pointless under UEFI, and only serves to handicap you)

along with this, a little reorganization of the wiki to make UEFI information/tutorials more prominent and BIOS information/tutorials a little less prominent
IMHO, we really should begin to push people towards UEFI, it is now at the point where even most of the old test systems people might have lying around are likely to support UEFI, and so we should really push people in that direction, rather than basing people on BIOS/grub and leaving UEFI as an afterthought

only consern would be what is the state of UEFI support on the popular emulators? (bochs, qemu, vpc, vmware, etc)


of course then the question is, do you have (or are willing to gain) sufficient knowledge of UEFI to write such a tutorial?

JAAman wrote:...of course then the question is, do you have (or are willing to gain) sufficient knowledge of UEFI to write such a tutorial?

And there's the problem with many tutorials, especially those providing "working" code -- they aren't really tutorials at all, they are the sketchy map someone has drawn when he worked his way through the jungle. Those who are really competent in a subject seldom return to write a good tutorial. (Exceptions nonwithstanding.)

The Bare Bones tutorial showcases those parts that will be unfamiliar even to proficient user-space programmers: The bit of assembly required to get into C space, writing to screen when there's not even a putchar() function to help you out, and writing a linker script to get it all working.

And I have to say, I like what zesterer has done here. It indeed makes a better impression at first sight. Personally I would have kept the FAQ in there, but it's his new concept, not mine.

Solar wrote:

JAAman wrote:...of course then the question is, do you have (or are willing to gain) sufficient knowledge of UEFI to write such a tutorial?

And there's the problem with many tutorials, especially those providing "working" code -- they aren't really tutorials at all, they are the sketchy map someone has drawn when he worked his way through the jungle. Those who are really competent in a subject seldom return to write a good tutorial. (Exceptions nonwithstanding.)

The Bare Bones tutorial showcases those parts that will be unfamiliar even to proficient user-space programmers: The bit of assembly required to get into C space, writing to screen when there's not even a putchar() function to help you out, and writing a linker script to get it all working.

And I have to say, I like what zesterer has done here. It indeed makes a better impression at first sight. Personally I would have kept the FAQ in there, but it's his new concept, not mine.

Thanks. Being quite new to OS development (but proficient enough to know my way around things by now), I thoroughly empathise with beginners. I'm not new to programming by any means, but teaching myself about OS development was an uphill struggle all the way. Of course, it should be like that. Because it's a complex topic. By and large, the wiki is a great resource, but the Bare Bones tutorials misled me in several ways: ways that introduced huge design faults into my early kernels and almost made me give up altogether. I don't think people should or need to go through that unnecessary struggle simply because they're new to the subject. Also, people going through those troubles end up reverting to asking people for answers (I know i did a lot, and I'm very thankful to those that taught me) but it shouldn't have to be quite like that.

As someone who is still going through the process I can concur that there could be a better way of presenting information. So some up front caveats I understand and to a certain extent agree with the approach of avoiding a hand holding approach by supplying code. I also understand this is a niche activity and a certain level of knowledge and experience is required before beginning - the beginners mistakes and what you should expect when embarcing on this journey I thought were/are well written. So my prior experience 30 years as a technical IT person, designed and written in assembler, C, C++, Java, COBOL, Ada, and a few other languages. I have written compilers, servers, JMS providers and many other quite technical solutions. Yet I still struggle to get my head around many of the issues because this is new territory for me - learing is part of the fun after all. I guess my principal issue is where to start as an example the A20 thing I am still not sure when I must versus when I can switch the gate - still experimenting. Perhaps this is a good example of the lack of an overview, I have the Intel documentation and I think I understand it, I am not wary of specifications. Too many words! I would suggest that the nitty gritty of HAL understanding is in a sense mechanical in that this area does not require innovation and lacks opportunity for creativity (could be wrong - still learning). So a bare bones could walk a more detailled path to get to the point of the creative part of the journey. I would be happy to collaborate on improving the bare bones to become more tutorial like.