Development Documentation Refactoring

[kallisti5]

We really should reformat our developer documentation.

• User Guide
  • ​https://www.haiku-os.org/docs/userguide/en/contents.html
  • Generated from docs/userguide in git
  • Each language packed into haiku_userguide_XX hpkgs
  • "User Guide" Icon installed on desktop
• Developer Guide
  • ​https://www.haiku-os.org/docs/api/
  • Generated from docs/user in git
  • URL "api"
  • Called "Haiku Book" (aka like BeBook)
  • Not packaged, only on www.haiku-os.org.

Ideally, I think we should make the following changes:

• Move code to docs/developerguide
• Package like userguide (haiku_developerguide*.hpkg)
• Add an icon to the desktop "Developer Guide"
• Move document to haiku-os.org/docs/developerguide (and make /docs/api a redirect)

I honestly didn't even know where the developer guide lived given the odd / inconsistent naming within our sources.

[jt15s]

Totally agree with this - we can even consider moving in some of the other developer documentation from our website into the Developer Guide.

[nielx]

Replying to kallisti5:

Ideally, I think we should make the following changes:

• Move code to docs/developerguide

Why not stick to docs/haikubook?

• Package like userguide (haiku_developerguide*.hpkg)

The downside is that we would introduce a dependency on Doxygen during build. It is a fairly common package, but there is a chance that we would have to be very specific about which version to use if we want consistent output. Some Doxygen versions have bugs that cause weird output problems.

I also wonder whether we need to add things like the HIG in there.

Alternatively: should this be part of the haiku_devel.hpkg?

• Add an icon to the desktop "Developer Guide"
• Move document to haiku-os.org/docs/developerguide (and make /docs/api a redirect)

Again: why not Haikubook?

[pulkomandy]

I honestly didn't even know where the developer guide lived given the odd / inconsistent naming within our sources.

So, there is some history behind this.

Originally, there were two directories for documentation:

• docs/develop: internal documentation for Haiku developers (that is, people working on the OS itself)
• docs/user: documentation for people writing applications for Haiku. I guess at the time they were the only "users" considered, since Haiku was not in a state where it would boot to the desktop or the like.

Later on we got actual users and added docs/userguide for them.

I would keep the "API" for the Haiku book (​http://api.haiku-os.org is short, easy to remember, and clear enough). It would make sense to move the sources for it from docs/user to docs/api or similar. The name "API" is clearer to me, especially for people who don't know what the Be Book is/was.

I honestly didn't even know where the developer guide lived given the odd / inconsistent naming within our sources.

Whatever we do, please do not mix together the Haiku Book (which documents the API for people writing applications), and docs/develop and the website (which document the internals of Haiku and is useful for people working on the OS itself).

[kallisti5]

Keeping the development guide and api guides separate seems fine to me. We just need to clean up the naming and packaging to be consistent.

As for "HaikuBook". I get why people want to use it, but it doesn't convey what it is in any way. Using a branded "name" for something only works if it is within a small grouping of clearly branded items.

Clear:

• userguide
• developerguide
• apiguide

Clearish:

• userguide
• HaikuBook (aka apiguide, aka developerguide, aka 'user')

Unclear:

• userguide
• developerguide
• HaikuBook (aka apiguide aka 'user')

If we go for HaikuBook for purely nostalgia reasons, we're putting our nostalgia over the usability of documentation for users and developers. I like HaikuBook, I just don't think it makes sense when we want 3+ sets of documentation.

[kallisti5]

As a middle ground:

• userguide
• apibook
• devbook

book being "more complex" than a guide :-)