How to improve docs related to contributing?

[jt15s]

Wait - we still need to add in the link to Netlify. Any ideas on where we could put this?

[leavengood]

I think I can handle this. You’ve provided a lot of help just doing the research.

I figure we can add the Netlify banner in the footer on the website template, and after I have stuff in place I will fill out that form.

I appreciate the help! Sometimes we just need someone to do the annoying research

[jt15s]

No worries! Always happy to help

While we’re at it, Docker also has an open-source program:

Docker Open Source Support

Haiku uses Docker containers for its website, so maybe we could consider filling out an application to see how Docker can support Haiku: https://www.docker.com/community/open-source/application As said on their website: Docker is committed to supporting the open source community and we thank our open source community for their contributions. Please complete our application to get more information about how Docker can support your open source project on Docker Hub. Would this be suitable fo…

[q5sys]

So, speaking for myself here, I’d love to help contribute to the documetation if there was an easier way to do so. I tried to make a single line commit previously but dealing with Gerrit got me all confused and I ended up making a mess of it… as some of you may remember. Eventually my change was unneeded, since I was able to archive the docs being referenced into the Haiku website.
Im more than willing to help convert the existing docs that are in the wiki onto the site, but I’d want direction from the Team for how they want it structured before I put in work that has to be redone.

I know from looking around earlier, that some of the docs seem to be written so that they can be generated with DocsyGen, which I’ve never used before and obviously there’s a learning curve there to understand how that works before someone can pitch in and help improve the docs that are generated with that.

This past year I’ve been working as a Validcation and Documentation Engineer for iXsystems (the people behind FreeNAS and TrueNAS, converting from their old sphinx docs system to a new git based hugo docs site) and running their Security Hugo Site. So Im ready to go on anything you guys want to throw at me on that front. If I can avoid having to have a dedicated system for doing commits through the haiku git instance and dealing with gerrit… I’m happy to dive in.

But that of course is all contingent on you guys deciding that you want the docs hosted on the Haiku website and not somewhere else.

It’s you’re project, so its your choice. If I can help, Im happy to do so.

[PulkoMandy]

@q5sys

So, speaking for myself here, I’d love to help contribute to the documetation if there was an easier way to do so. I tried to make a single line commit previously but dealing with Gerrit got me all confused and I ended up making a mess of it…

If you don’t want or can’t use Gerrit, you can submit your changes in other ways (attach patches on the bugtracker, send us link to a git repo elsewhere where you have them, etc). Gerrit is a nice tool for code review but if you don’t want to use it.

As for “making a mess”, I already forgot about it. It happens regularly and it’s always possible to fix.

Personally I prefer that changes get on Gerrit (even if not in perfect shape) rather than having to track them in the bugtracker, in git repos all over the place, etc. But, I can adapt myself.

The use of Doxygen is very simple. It is documented here: HOWTO « user « docs - haiku - Haiku's main repository but essentially it’s this:

• Go to the directory where the “Doxyfile” is (docs/user in our case)
• Type “doxygen” in a Terminal
• The HTML files are generated

@q5sys

If I can avoid having to have a dedicated system for doing commits through the haiku git instance and dealing with gerrit… I’m happy to dive in.

I don’t understand what you mean by “a dedicated system”. To send patches to Haiku you need to use the git command line tool, that’s all. If you know how to do a git push, you’re all set.

So, in the short term: don’t worry about Gerrit and making a mess on it. We’ll be here to clean things up. Or just put your changes elsewhere and we’ll find a way to integrate them.

[jt15s]

Whilst we are figuring out what medium to use, I think we can take this opportunity to integrate a proper search function into the main site; which is the only gripe I have with the main site. Currently, it utilises Google search which is not very convenient nor intuitive.

Hugo recommends several open-source and commercial search solutions which can be easily integrated into the main website:

Search for your Hugo Website

[jt15s]

I think that this discussion has come down to the following, please correct me if there are errors:

• Users are being discouraged from contributing to documentation since the site uses Git.
• We could consider using Doxygen to generate the new documentation website.
• Any moved documentation pages need to have redirects so there are no major problems with navigation.
• The documentation needs a good sorting/reorganisation.
• It may be a good idea to decouple the documentation from the main site for organisational reasons (the documentation is defined as any specific technical documentation related to Haiku)

I feel like we might be able to consider using Hugo - we could use one of the documentation related themes on their site. @q5sys could help us out, and I’ve just discovered that there are several FOSS and proprietary GUI-based Content Management Systems for Hugo sites:

Frontend Interfaces with Hugo

This means that the issue of “scaring” new contributors away will be alleviated, as all one will have to do is access the user-friendly CMS to edit pages.

[leavengood]

I believe Haiku needs three levels of documentation:

1. User documentation. This should be covered by the user guide and I believe we think this is in good shape?
2. API documentation and related documentation for developing Haiku applications and using the various APIs and Kits. This is where Doxygen would come in and also some other nicer tutorial articles like stuff Jon Yoder (aka DarkWyrm) wrote and even some of the older BeOS development books. Though more content here would be good, such as videos or updated articles on newer Haiku concepts like HaikuPorts and the package system.
3. Documentation on building and developing on Haiku itself, both at a general level and for specific sub-sections of the OS. I believe this is the part we feel is in the worse shape. The organization on the website is kind of spread out, and detailed docs about specific parts of Haiku are spread out in the Git repo, Wiki and maybe the website (or they don’t even exist.) I think this is the part that needs the most work.

I’d have to think about it a bit to come up with a really solid plan but my general thought would be to work on improving the initial “I am new to Haiku and want to compile and make bug fixes” situation. This might mean moving things into a single big page with most of the details at a high level. It would be nice if there was a way to select the operating system someone is using and have that update the page like can be seen on a lot of programming language document pages. This document can link to some of the other more detailed pages maybe, or maybe some of those can be eliminated. An example here would be to have the main page quickly talk about the build profiles and the defaults that someone should use initially, and then link to a page with details about the UserBuildConfig file if they want to customize things.

As for details about the kernel, app_server, the package kit, etc, I think having those in the Git repo or Wiki is fine, but it would be good to be consistent and it would probably also be nice if they could be linked to easily and read on GitHub, which would mean README.md or another language which GitHub can display in a nice way. Or maybe something which can be read in our Git web server which might have more limitations.

We may have to experiment some.

[PulkoMandy]

@leavengood

API documentation and related documentation for developing Haiku applications and using the various APIs and Kits. This is where Doxygen would come in

This is where Doxygen already does come in. The result is available at api.haiku-os.org
This part works fine. It is maintained in Git because it’s normally updated alongside the code (when we add or change APIs, for example). I’m not sure moving it out of there is a great idea.

@leavengood

also some other nicer tutorial articles like stuff Jon Yoder (aka DarkWyrm) wrote

This one is currently hosted on some user’s github: GitHub - theclue/programming-with-haiku: Learning to program with Haiku and Programming with Haiku books
We should make it probably more “haiku-official” and easier to browse online.

@leavengood

even some of the older BeOS development books

The Be Book is available from Haiku website. We have a creative commons “no derivative” license for it, which means we can distribute it, but not update it. That’s why it is separate from the new Haiku Book, and eventually needs to be replaced when the Haiku Book is complete.

Finally, in that second category you forgot to mention the Haiku Interface Guidelines and Haiku Icon Guidelines.

@leavengood

Documentation on building and developing on Haiku itself,

And yes, that’s maybe the hardest part, but also the one where I think it’s most difficult for non-developers to join?

@leavengood

it would probably also be nice if they could be linked to easily and read on GitHub, which would mean README.md or another language which GitHub can display in a nice way. Or maybe something which can be read in our Git web server which might have more limitations.

I would prefer that we don’t rely on Github for anything.

Anyway, I think the first thing I would consider is reorganizing what’s already on the website.
Currently you can find documentation in:

• The developer’s blogs. Often written once and never edited, it ends up being mostly for historical reference.
• The documentation section, for technical things about Haiku internals. On the old Drupal website there was an autogenerated list of available documents, which has disappeared with the website migration (the closest approximation is Articles | Haiku Project).
• The development section, which has some documents on how to build Haiku
• The “guides” section at Haiku Guides | Haiku Project which was added because even ourselves can’t understand very well what the difference between “development” and “documents” is. So we did what someone does in that case - created a new folder and ignored the old ones. This is the section with basic information on building and compiling haiku. The big problem is it is not an “official” section and is not available in the website header like the others.

So, that’s what I would start with: reorganizing the website so that we have the organization we think would make sense: user documentation, application writers documentation, and haiku internals documentation. Replacing the current “development”, “documentation”, “guides”, and “articles”.

I think once we have done that, the state of the website will be a lot clearer. That is already a great improvement. Then we can decide if some of these pages should be moved out of the website, or if other things should be included into the website.

[jt15s]

@PulkoMandy

So, that’s what I would start with: reorganizing the website so that we have the organization we think would make sense: user documentation, application writers documentation, and haiku internals documentation. Replacing the current “development”, “documentation”, “guides”, and “articles”.

I think once we have done that, the state of the website will be a lot clearer. That is already a great improvement. Then we can decide if some of these pages should be moved out of the website, or if other things should be included into the website.

I agree - sounds like a good plan to make sure we don’t take lots of work on at once.

@PulkoMandy

This is where Doxygen already does come in. The result is available at api.haiku-os.org
This part works fine. It is maintained in Git because it’s normally updated alongside the code (when we add or change APIs, for example). I’m not sure moving it out of there is a great idea.

Doxygen is fine - it is able to generate well-designed documentation etc. - but I find that it feels quite uncoupled from the main site and other documents - i.e. links back to the main site as well as to any related documents should probably be added.

@PulkoMandy

So, that’s what I would start with: reorganizing the website so that we have the organization we think would make sense: user documentation, application writers documentation, and haiku internals documentation. Replacing the current “development”, “documentation”, “guides”, and “articles”.

I agree with this organisation - although I don’t really understand why we need two different sections for application writers and haiku internals - couldn’t those just be one unified “developer documentation” section?

Also, the HIG guidelines may need to be redone using Doxygen: the current one lacks any navigation/usability:
https://www.haiku-os.org/docs/HIG/index.xml

Additionally, if we are to keep all the documentation we have on the main site and maintain the site as an entry point for people looking for documentation, something we need to consider is adding a native search function to aid navigation.

[PulkoMandy]

@jt15s

I agree with this organisation - although I don’t really understand why we need two different sections for application writers and haiku internals - couldn’t those just be one unified “developer documentation” section?

No, they are completely different things.

People writing applications want to have reference to the public APIs and how to use them.

The internals are internals and should stay as such. People writing applications do not need to know technical details about the use of a memory management unit, where to find documentation for the SPARC CPUs, how the SD card driver is implemented, etc. That is the kind of documents you find in the “internals” part, also with information on how to submit patches to Haiku, how to recompile it, how our sourcecode is organized, etc. None of this is useful to application developers, just like none of the API reference is useful to normal users (who don’t even need to know what C++ is to use Haiku).

In the current situation, there is a large overlap. This is because 1) we advertise the OS as beta and attract mostly (but not only) users who are also developers and 2) the OS is unfinished, when you write an app, you can often run into problems and end up digging into the OS sourcecode. But these are issues we should resolve, I think, not a situation we should make worse by mixing up all these different documentations.

@jt15s

Also, the HIG guidelines may need to be redone using Doxygen: the current one lacks any navigation/usability:

It’s a single page. It could be a single Doxygen page, that would not change anything. What do you think is missing? A table of contents at the top? I can have a look at improving the xslt stylesheet for it.

@jt15s

Additionally, if we are to keep all the documentation we have on the main site and maintain the site as an entry point for people looking for documentation, something we need to consider is adding a native search function to aid navigation.

I think having the API reference / application writer docs as a separate site is better. The main website is too big and confusing. Let’s first make it less confusing, then we can see about splitting it if needed.

[lelldorin]

@PulkoMandy

I think having the API reference / application writer docs as a separate site is better. The main website is too big and confusing. Let’s first make it less confusing, then we can see about splitting it if needed.

Some times we can add a link to the other section, if this makes sense. I agree with pulkomandy

[waddlesplash]

@jt15s

Currently, it utilises Google search which is not very convenient nor intuitive.

We used to use an embedded Algolia search, but we decided that we actually preferred the Google search interface and results, so let’s leave it that way for now.

@jt15s

Users are being discouraged from contributing to documentation since the site uses Git.

Git is pretty easy to use these days, especially if you use GitHub Desktop or something like that. And we can help people get started if they are confused.

@jt15s

We could consider using Doxygen to generate the new documentation website.

Huh? The API docs are already generated with Doxygen…

@jt15s

It may be a good idea to decouple the documentation from the main site for organisational reasons (the documentation is defined as any specific technical documentation related to Haiku)

Probably most of the more technical documentation (e.g. about Kernel Debugging Land) should be moved off the website and into the source tree, both for better discoverability and because that is where it really belongs.

@jt15s

I feel like we might be able to consider using Hugo

We are already using Hugo…

@jt15s

This means that the issue of “scaring” new contributors away will be alleviated, as all one will have to do is access the user-friendly CMS to edit pages.

I do not really know how many people want to contribute but do not because of a lack of a CMS. Maintaining a CMS, even one that works with a flat-file Git repository, is a lot of work. It may be easier for such contributors just to send us files with the pages they have written, and we can post them.

[jt15s]

@PulkoMandy

No, they are completely different things.

People writing applications want to have reference to the public APIs and how to use them.

Understood. Thank you for clarifying!

@PulkoMandy

It’s a single page. It could be a single Doxygen page, that would not change anything. What do you think is missing? A table of contents at the top? I can have a look at improving the xslt stylesheet for it.

Personally, I think it should have the same design as the API documentation, this would make it more consistent etc. And yes, a table of contents at the top would help a lot, as would adding categories of links up the top to different parts of the documentation as is present in the API documentation.

[jt15s]

@waddlesplash

Git is pretty easy to use these days, especially if you use GitHub Desktop or something like that. And we can help people get started if they are confused.

I agree - maybe I could put together a guide for using that too

As a newbie to Github I use Github Desktop and it is indeed really easy to use.

@waddlesplash

Huh? The API docs are already generated with Doxygen…

Apologies for the confusion: parts of the post you are quoting are already outdated, since @PulkoMandy decided that we should work on sorting out the website before deciding on what to use for external documentation. I was proposing that we could use Doxygen for the other documentation too.

@waddlesplash

We are already using Hugo…

Again, this was an outdated remark: back then I was thinking of separating the documentation from the rest of the site and having a separate, new site for documentation.

@waddlesplash

I do not really know how many people want to contribute but do not because of a lack of a CMS. Maintaining a CMS, even one that works with a flat-file Git repository, is a lot of work. It may be easier for such contributors just to send us files with the pages they have written, and we can post them.

Again, that is quite true. And we can solve this issue by suggesting people use Github Desktop as you mentioned.

[jt15s]

Updated flowchart to reflect subsequent decisions/discussions:

[jma_sp]

Just for proposing an idea.
Looking as the wiki of this site is working, letting people create, translate in several languages with change history and code (powered by wikimedia)…
Mantaining visual style of Haiku web.

https://www.lazarus-ide.org

https://wiki.freepascal.org

[jt15s]

Thanks for your suggestion!

Right now, we are looking to reorganise the content we have currently to make it easier to find.

After that, we will look into moving any content hosted on Trac and Github into the site as well.

We have decided not to go down the path of implementing another platform to put documentation since it may confuse people, and especially for software like MediaWiki, it means that our sysadmins have yet another thing to look after.

Thanks!

[jt15s]

Also, just wanted to point out there is an unofficial WikiBook on Haiku:
https://en.wikibooks.org/wiki/Haiku

Maybe we could figure out what to do with this?