How to improve docs related to contributing?

Community
1

The SubmittingPatches guide and the Compiling Haiku guide are in separate pages. Pages on contributing are split across pages that can only be found on Google and/or are too complicated, inconclusive and fragmented (Exhibit A, Exhibit B).
The point is that contributing to an entire operating system is a pretty intimidating idea in itself and the words “everyone can contribute” definitely aren’t persuasive enough, despite it being true.

In short, the way different pieces of information are scattered across different sites, an overall lack of clarity as to what people can do and listing all sorts of people that could help (rather than mentioning projects directly, providing beginners with instructions and giving some sense of direction) makes people think that they’re not “qualified enough to contribute to a project as big as this”, which ultimately drives people away.

From my experience, there seems to be a lot of people that have expressed an interest in the operating system-- and, apparently, a number of potential contributors that’s interesting enough to the point where I think that the elephant in the room needs to be finally addressed; How do we improve the documentation in order to attract more people?

2

I’ve been trying to reach out to people interested in Haiku in order to convince them to actually give contributing a shot lately.

As a person who arrived here from a community outreach program (Google Code-In), I got the idea to e.g. recommend a few simple tasks as a means of getting used to contributing. That being said, I think that it’d be a very good idea to come up with something like that that in the documentation itself (I only found out about that EasyTasks section in dev.haiku-os.org today!)

I’m mostly just seeking after the community’s feedback right now, and I’m looking to discuss ideas.

1 Like
3

I think there can never be one page with all the info on every detail on how to contribute code. One thing leads to another and as long as links are connecting those pages, it’s OK.

The Development FAQ on the sidebar of the top Development page is the logical entry page for new devs. It has the links to building from source, coding guidelines, how to submit patches and to the Getting Started page which lists introductory tasks, including those EasyTasks on Trac.

If anything is missing or could do with more details, I’d say add it to the FAQ or Getting Started page.

4

That one is extremely bound to developers only. The other links I provided provide information relevant to development.

I think that this page in particular is good, but, for instance, I wouldn’t agree with the ambiguity of this page– the contents conflict with the contents of that page.

5

I think that the documentation is messy and that many different aspects of contribution-related documentation need many different readjustments, so that the reader is led by the hand accordingly, as if they were looking at some sort of a flow chart.

For instance, I managed to convince a person to check out HaikuPorts by telling them to check out “how to update a recipe”, read the wiki, and then try to move on to porting their desired software and consult the IRC If necessary.

There are many people that want to but cannot understand how to help, despite the documentation being out there. I strongly believe that this means that the documentation is undeserving the community in its current form.

6

Your post referred to development intro docs only, so that is what I looked at.

I’m not sure what you mean with “ambiguity” here. One page is targeting (OS) developers, the other every other kind of contributions. The (non-coding) Getting Involved page lists the wide variety of departments to help with, each linking to more info in that area.
I’m sure things can be improved, but I have no concrete idea what exactly. If those pages are restructured, just make sure nothing of the (alledgedly) spread out info is lost… :slight_smile:

7

The main problem, I think, is the organization of the website itself. There are 3 main sections nammed “community”, “development”, and “documents”. This makes no sense to me, because our documents are for developers, the developers are part of the community, and so on. So it’s unclear where to search for things, and more annoyingly, it’s unclear where to store things.

This organization was partly inherited from the previous Drupal based website. Already then, the person working on the site wasn’t too happy with the organization, so they created a new tree: Haiku Guides | Haiku Project for the “actually useful” docs. But that is not integrated at all with the website organization.

Another problem is that currently the website uses Git. While that’s fine for developers, I think it will turn away some non-technical contributors who would otherwise be happy to edit and improve pages. Even for developers this can be a bit annoying, and as a result, some things land on the trac wiki instead because it’s easier to put them there. And then there was some effort to move some docs from the wiki to the haiku sources directly, in the docs/ folder. Which isn’t great, because the only way you can see these files with markdown formatting now, is by using github.

So, long story short, the whole thing is a mess, and I wouldn’t know where to start to fix it. I’ve considered participating in Google Season of Documentation where we could get a technical writer to help with this, but we need someone willing to write a project idea for it and handle the mentoring (and the application process). No one wants to do it.

There’s a risk of “wiki disease” here. I’ve seen this happen typically on Linux distros community support wikis. These wikis usually start out great, but as time passes, the technology changes, and people never dare to remove old info in case it is still useful. So you end up with pages and pages of info for Ubuntu 8.04, then a list of report from various users telling what they had to change for later versions.

At some point, we indeed need to clean things up, and that may mean removing some information so that each thing is in a single place. I don’t think we should burn the website to the ground, but “what information should we remove?” is something we should ask ourselves.

8

This could easily be resolved gradually if we solved the first and foremost problem that you brought up; “We have no idea where to begin”.

If we did have something like a flow chart, we could go by a specific plan and structure that people could easily build on top of, before commencing with the restructuring of the website. We wouldn’t need to think about what needs to be rewritten excessively, and we could focus on putting the relevant content in its predefined position. That choice alone would mean implicitly planning ahead what needs to be written or, more importantly, rewritten/adjusted, condensed or removed. Afterwards, if we come across something that’s out of place, we could immediately begin with figuring out where the contents of the file need to go, if they’ve been regurgitated before, or if they need to get deleted instead.

9

FTR: I do like the way the “Development” page is organized, although I’d prefer to see something like a guide, rather than a directory with links, and ranking entries based on the level of difficulty and required experience.

10

Something interactive would be brilliant.

11

Hi all,

I’ve just been following this discussion and want to (try and attempt to) help sort things out, and as @n0toose has suggested, I will try and provide starting points from where we can work things out.

  1. One issue @PulkoMandy has raised is that the organization of the website isn’t very good, and that there are multiple places for documentation. We could try and figure out a place to store all the documentation (I’m thinking the main site is probably the best option, but then again, others probably know best) and then move all documentation into that space. We should probably create a temporary “holding space” to put all this documentation as a first step. Then, we could work from that space and try to sort it out (i.e. removing redundant or old documentation), and then move the sorted documentation into the permanent place.

  2. Another issue raised is that Git might turn away potential contributors to documentation. One way we could go about this is moving all related documentation into a new, consolidated home, separate from the main website. We could consider using something like read-the-docs (which provides free hosting) or a wiki (although, as pointed out, a wiki could become outdated and “dead” quite quickly). Since I don’t know much about Hugo, I’m not sure if we could implement another newbie-friendly way of contributing to the website.

@bitigchi and @n0toose have suggested we make a flowchart, which I could do relatively quickly with the handy flowchart designer I use, so I’ll try and work on a draft.

Please let me know what you think about this.

Thanks!

2 Likes
12

As promised, here is the first draft of the flowchart. Please view the image in another tab if you can’t read the flowchart properly.

Haiku Documentation Reorg

Thanks!

13

I think at least a part of doc on HaikuPorts and Haiku Depot Web should also be included.
You shouldn’t have to search in several places to know how to make a proper recipe and make your package looking good in HaikuDepot. And, even more when you intend to use it only locally.
Who knows? It may also help in emergence of new repos.

2 Likes
14

I agree - I had a look at the documentation for HaikuPorts and wondered why it was on Github Wiki and not on the main site documentation.

15

Because haikuports is not haiku but a separate project. There is some overlap of the teams working on either, but not completely. And also because the website is not a good place to put technical documentation. The github wiki works very well for that.

1 Like
16

Thanks for the clarification - I didn’t know they were separate projects.

1 Like
17

Alright - now we have a rough idea, I think we can start planning.

Where do you think all documentation related to Haiku should be kept? I was maybe thinking maybe making a documents hub with a URL like docs.haiku-os.org and then hosting all the docs there. However we have to figure out what to use here. Do we use something based off the main website? Do we use a wiki? Or do we use a more specific documentation solution like Gitbook (which is free for FOSS projects) or Read The Docs (again, free for FOSS projects)? If anyone has any suggestions or alternative proposals don’t be afraid to speak your mind.

18

There is already a kind of document hub : https://www.haiku-os.org/documents/.

Is it something like that you had in mind ?

19

Yes, at that location but probably separate from the existing site. Personally I think that the main site is better suited to hold blog posts and general information, whilst all other documentation should be decoupled from the existing site. The existing site also relies on Google Search to search the site, which is a bit unintuitive and inconvenient.

20

The current approach is having the docs in the docs/ directory of Git. Apparently it is the only way to make sure developers think of updating them.

Some are in doxygen format and could be used to generate something similar to api.haiku-os.org for developer/internal documentation. Some are just text files.

That’s for the technical documentation of Haiku internals. I don’t know if the documentation about contributing (submitting patches, using git, the review process, how to build Haiku, …) should be in the same place. I think using the main website is more appropriate for that, because these docs are for people interested in joining the project, and they should be quite easy to find from the website which is our entry point.

That’s somewhat true for the current version of the site. The previous versions using Drupal had better support for the documentation side as well. I think it could be re-added into the website.

Also one thing we worry about is creating dead links in the process. It’s nice to want to reorganize things, but you have to keep in mind that there are links everywhere: on the website in blogposts, in the forums, in the sourcecode, etc. Moving a page without care will break these links. So, at least some redirection should be set up to avoid that.

2 Likes