How to improve docs related to contributing?

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?

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 today!)

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

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.

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.

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.

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:

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

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.

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.

Something interactive would be brilliant.