Is there a book describing Haiku development from A to Z?

I think that’s a bit harsh. FWIW, I believe most of the devs and this community at large don’t take offense by people expecting something without contributing themselves. Often, as newbies, they realistically can’t. Also, I think many experience Haiku’s rather polished (IMO) feel and expect a larger dev/community than we really are.

We do it all for ourselves and each other. If more people join, that’s great, but it’s not why we do it.
It’s when people get belligerent and ‘demand’ things, or tell us what and how to do it without having any stake in it, that it gets annoying and we get protective of our community.

[I wish you strength and good fortune, dbs, for your current RL struggles!]

5 Likes

@Tarasenko I believe that this is a great opportunity for someone like you to start working on such a book, since it sounds like you have the vision of what should be delivered. You could document the development process as you discover it and pitch it at the right level for your audience.

2 Likes

Is that all we have to reply, “just do it yourself”?

The problem is not really the vision. We already know what should be in the book and it is painfully annoying to not have it. A massive amount of time is wasted by people trying to join the development team and struggling to find the info they need, as the only way to do it is… to ask the people who know, over lengthy email threads and IRC chats.

We really should do better in that area, and we’re not going to do that by asking newcomers to write the docs themselves. Otherwise, we are going to remain a small team, with people outside it who will continue to say “I would contribute if only I could understand how any of this works”. This applies to all things: the coding guidelines, how to submit a patch, how and when someone can get commit access to the repository, how is a driver written and what components are involved, etc. Some of these things are factual and technical and can simply be documented, but others need to be debated because they are not written anywhere and each of us possibly has a different idea about them. And we can’t expect someone outside the team to be able to achieve that. How do I know? Because the last attempt ended in disaster. See this pull request that has been open for 2 years: Organized Haiku Guides by n0toose · Pull Request #506 · haiku/website · GitHub the person who did this is now involved in Serenity OS instead, because the community there was far more welcoming.

And indeed this thread, with one person replying with insults and another with “just do it yourself” certainly does not help with improving on this.

9 Likes

Yes, unfortunately you hear the “do it yourself” too often.

Even as part of the Google summer of code, writing documentation is not necessarily the right thing to do, since people who have a lot of time to explain something are also needed for support (to get straight to the point :wink:).

The problem is that the developers have to deal with programming, problem-solving and, due to pressure from the community, have to keep working on new betas :wink:.

Not every programmer can write instructions, that’s the way it is. There are people who find it easy and others who have difficulties with it. I could, but I don’t have the necessary knowledge about programming because I think there is a lack of documentation for programmers in particular.

There are instructions for the system in parts (Haiku Guides, BeSly knowledge base …). It is therefore difficult to find someone who, firstly, has the necessary experience with programming haiku and, secondly, likes to write. I think that’s the real problem.

1 Like

No it wasnt “just do it yourself”. It was: If you have the itch, scratch it. It was a gently delivered suggestion of the idea to help and contribute.

In fact, I’d say it was much softer than “patches welcome”, something I can quote from you 16 times, according to forum search results.

Writing a book will take a full time developer away from developing. And I see someone asking that “funds will be made available”, when there are barely funds to cover the one paid developer already working for the project. When, in fact, it looks as though the funds to pay that developer could run out if donations dont increase. And somebody who asks this question cannot be aware of the current lack of resources in the project and the fact that they might be able to help.

If you think that some developer resources are better spent on writing documentation, and that it cant be done by a newcomer, then I am inclined to agree with you, because I dont have the relevant experience to make that judgement. But I don’t understand the need to misquote and lambast me for suggesting that someone might help themselves and others by contributing.

2 Likes

I don’t. What should be in it that isn’t already documented somewhere else? I don’t mean to be ironic, I’m asking seriously.

2 Likes

And can it be serious, that if ALL infos about Haiku were available but neatly divided into categories, that the OP would still complain about it not being a single book? I mean there are many different categories like Haiku history, architecture, driver dev, app dev, various APIs.

Starting with simple things:

  • The source repository directory layout
  • The main jam targets used in Haiku
  • The buildtools repository, what’s in it, why it exists
  • How to navigate the bugtracker and find things to work on (the current instruction is “look at this list of 5000 issues and find something interesting”)
  • The governance of the project, how do people get commit access, how there are no “maintainers” for specific parts of the code and everyone is expected to know everything, how that can’t possibly be the case so there are, in fact, default owners for each compoment in Trac that provide a good idea of who is responsible for each component. How we communicate, which channels we use, why we have chosen them (free software tools, and asynchronous modes of communication), what their limitations are, what we are doing about it (such as using the forum more and the mailing lists less)
  • An up to date documentation on how to write and run unit tests (the current doc is 3 different blog posts, one of which still references CVS as the place the Haiku source are stored)
  • Tips for efficient testing and debugging: how to use network boot to quickly iterate on testing a driver, how to make best use of qemu, how to test changes to an application or library from inside Haiku without rebooting and recompiling a full filesystem image

More “in-depth” stuff:

  • Documentation for the internals of each “kit” and “server”, for example, how the net_server loads network drivers, how it assign network protocol to each network interface
  • A complete and up to date guide to the driver architecture, how busses and bus_managers work, etc
  • Complete and up-to-date documentation on the graphics stack, including the remote_app_server with both the html5 and native backends, and the test_app_server
  • Proper documentation for the file cache and block cache and the vfs, and what services are provided by each of these, and how they connect to filesystem drivers,
  • The policies for ABI stability for releases and beta versions, and the various things we have set up to avoid breaking applications all the time: libshared, symbol visibility, “fragile base class” padding
  • Documentation on porting Haiku to a new architecture, where to start, how to use bootstrap builds and how to avoid using them since they don’t actually work, tips for debugging the early boot process on both real hardware and virtual machines.

I think that would be a good start? Anything missing?

10 Likes

I used to say this, but someone complained about it a few years ago and they are correct. So I use it more carefully now, either when answering someone who is already a member of the Haiku community, or when someone act like they know everything or say something along the lines of “this should not be very hard to do”.

Here, the request seems perfectly reasonable to me. Our documentation deserves to be better.

Your reply on its own I think would be fine, but it arrived unfortunately after a less politely worded message, and as a result, ended up adding to it and creating something that probably makes newcomer feel rather unwlecome. This is probably unintentional from you, but it is how I perceived it.

And I guess I’m a bit tired and should spend some time away from computers this week-end and come back in a more calm state. Sorry about that.

3 Likes

Thanks @pulkomandy for the detailed list. :+1:

2 Likes

Well, I’m sorry to have given that impression, then. I will stay away from suggestions like this in future, so I learned something too.

1 Like

Yes,500 euros in 2022.

4 Likes

Entered as ticket 18473 :smile: (Don’t worry. I saved you the trouble. Should it have been multiple tickets?)

3 Likes

This topic is temporarily closed for at least 4 hours due to a large number of community flags.

This topic was automatically opened after 4 hours.

If you can get a hold of the original “Programming BeOS” book, that would be a lot of help. Of course, that book doesn’t cover some of the newer stuff added by the Haiku project, like the Layout Library for UI, but it gives you a good overview. There is a used version for sale on Amazon…a little pricey though…

https://a.co/d/7bPDwEd

There is also this book written by Jon Yoder…Learning to Program with Haiku

https://a.co/d/bhJXLGb

1 Like

O’Reilly made the Programming the Be Operating System book free in PDF form some years ago:

https://www.oreilly.com/openbook/beosprog/book/

3 Likes

I put the PDF’s in a single ZIP file for ease of access…

https://www.codewrangler.com/download/haiku/ptbos.zip

1 Like

It’s also available as a single pdf from the Documents page.

2 Likes

Thanks, that was the link I was wrongly refering to above :slight_smile:

1 Like