How to improve docs related to contributing?

We already have one even if it’s not called that way: https://www.haiku-os.org/community/organization/policies/

2 Likes

That’s even better - Netlify requires us to clearly call it a Code of Conduct and link it in the Haiku repositories etc.:

So, if that’s fine with everyone, could someone go about doing that?

In response to @leavengood’s concerns about people misusing the Policies/Code of Conduct, personally, I think the existing one is as simple and as fair as possible and it’s hard for people to turn such a document into a “weapon”.

1 Like

Including a docs/ section would only really appeal to… well, developers, and it splits work across different places. If the website could include the documentation included in the repository and dynamically update it, that would be more than perfect AND future-proof.

3 posts were split to a new topic: Code of conduct / community guidelines

We discussed adopting it at some point in the past and decided against it for a variety of reasons. The “Community Policies” page is our equivalent of a “code of conduct”, and it has served us well enough so far. Perhaps we need to tweak it a bit, but at least I do not think we need to replace it entirely.

Well, we call it “Community Policies”, isn’t that sufficient? If Netlify does not care what is in the document, only that it is called a “Code of Conduct”, that would not make much sense.

3 Likes

Yeah, preferably we should just keep it the way it is, but @leavengood asked whether we had any alternatives to hosting because we were paying quite a bit for Netlify hosting.

Netlify has an open-source program which provides free hosting but with the same benefits as our current plan - with some added requirements:

  • Includes a license listed on the Open Source Initiative approved license list or a Creative Commons license that includes “attribution” or places the work in the public domain.
  • Features a Code of Conduct at the top level directory of the project repository or prominently in the documentation (with a link in the navigation, footer, or homepage).
  • Must feature a link to our service on your main page, or all internal pages. You have two options:
  • We have premade badges for your convenience, or
  • You may create your own link, which should read “This site is powered by Netlify”, and include a link back to our home page.

As you can see the second dot point is the reason why we are discussing a Code in the first place. Although, I feel as our Policy page may suffice…

1 Like

For reference, here is the form we have to fill in:
https://opensource-form.netlify.com/

I don’t think Netlify can dictate what our Code of Conduct is, just that we have one. I say we just link to what we have.

3 Likes

I wholeheartedly concur.

Agreed! Do you want to fill it out?

They don’t say it has to be called “Code of conduct”. They just want us to have one.

The one we have is good enough.

1 Like

Agreed - it is fair and simple. No need to change something that works.

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

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 :wink:

2 Likes

No worries! Always happy to help :smiley:

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

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.

3 Likes

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: https://git.haiku-os.org/haiku/tree/docs/user/HOWTO 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

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.

1 Like

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:

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:

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 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.