Unified documentation

Feedback Ideas
1

Lately I have heard from many people who would like to contribute to Haiku development, whether at the application level, driver level, or kernel level.

One of the most common problems is documentation, but not because of lack of it, but because of the fragmentation of that documentation.

https://www.haiku-os.org/docs/userguide/en/contents.html
https://www.haiku-os.org/legacy-docs/bebook/index.html
https://www.haiku-os.org/docs/api/index.html
https://www.haiku-os.org/docs/develop/index.html

And that’s not to mention the various pages of blog content, mailing lists and forum threads on Haiku development.

Would any developers be willing to create a unified documentation?

I could do translations, mainly Spanish and Italian, and possibly Portuguese.

Anybody up for it?

3 Likes
2

The userguide and the developer documentation are aimed at two different crowds. I’m not sure they should be unififed. Also, Haiku doesn’t have permission to modify the bebook or to copy any of the text from it. So, the bebook can’t be unified either.

3

Then… What can we do?

New programmers, in many cases, do not know where to start.

2 Likes
4

Maybe by mapping the documentation and the blogs. Some little tidbits of information at the blogs do not appear at the “central” documentation ( the api part ) , and others are outdated. So, clarifying that , while also including examples when useful, would help many people a lot.

1 Like
5

It wouldn’t make sense.

There are 3 levels of documentation:

  • The userguide is for users.
  • The API reference and the Be Book are for developers wanting to write applications for Haiku.
  • The Haiku internals documentation is for the internals of Haiku.

So, new developers can start from the API reference. Hopefully they don’t hit a weird bug and don’t need to dig into the Haiku internals.

That being said, there is still a lot to be done and improved. As you mentionned, a lot of the documentation is actually not in any of these 3: it’s blog posts at best, or at worst you can only find it in some old IRC logs. So, help is welcome completing these 3 documentations, without merging them together.

A special note about the Be Book: we got permissions from Access Co Ltd (the current owner of BeOS) to redistribute it. Unfortunately, they chose a “no derivatives” creative commons license, which means we are not allowed to incorporate it in the new documentation. That is why this information currently cannot be included in the new API documentation.

They should start from the API documentation.

Let’s make a short test to check this, imagine I’m totally new to Haiku and want to start developing for it.

I go to the website: https://www.haiku-os.org
At the top of the site there is a section called “Development”, I click on that and get to Development | Haiku Project

I think this gives a good “where to start” page. Indeed, if some of the pages linked there were moved to the relevant documentations, this page could be simplified a bit, and that would be nice :slight_smile: For example all the “building Haiku” and “pushing patches to Haiku” should be in a section of the Haiku internals documentation.

There is also a FAQ page: Development FAQ | Haiku Project if you feel that new developers are getting lost, maybe that can be completed too?

2 Likes
6

I just want to take a moment and say this is a great attitude. You’ll find endless amounts of energy from our dev team to help anyone who wants to learn how to work on this stuff. We’re in desperate need of assistance for any and all tasks :slight_smile:

We’re all on IRC (oftc.net), and Matrix via the oftc bridge.

3 Likes