When you think about a software project, and specifically the people that are involved with it, you probably think about developers. After all, the code itself is what makes up the project. I submit to you that we have a perception problem in the software world. In fact I think we have it backwards. The software is the least important thing in your software project.
Currently, code commits get all the attention and metrics. They are typically what a project will use to measure progress, complexity, and really anything that is considered meaningful to the work as a whole. The fact is though, they're the last thing anyone who uses your software actually sees. It doesn't matter if you're writing client-side code, or a backend helper library: the first thing anyone will likely see, and the thing they will interact with the most is the documentation.
In today's software ecosystem code is cheap. Problems are relatively easily solved. What language you choose and what approach you take can often be a matter of personal preference and style. There are of course exceptions but these are far from the vast majority of situations. What really matters is how quickly the code you write can be of usefulness to anyone else besides yourself. Chances are you are not writing code in a vacuum (if you are, hello you have a weird setup and should probably join us in the 21st century, it's nice here). Think about the last time you used any software at all. Did you just intuitively know how to run it? No you had to read the documentation. It's strange then that the first thing we see has become somehow so low in our priority list.
Visibility is important
Now, I'm not just saying these things because it's what I've been doing lately. Ok yes that's exactly why I'm saying it. I've been trying to keep up with all the super awesome documentation help people are giving us on Ampersandjs and it has really made me realize how super important it is that the docs are right for everyone when they want to use that software. We all in the back of our heads probably realize how important documentation is, but rarely do anything beyond paying meager lip service. This is because visibility is important, it's only when you're knee-deep in it that you can appreciate something's importance.
Documentation is hard, I don't think anyone would disagree with this. It's also not prioritized. It goes way beyond just adding a few comments in your code (which I would argue is the opposite of documentation). Part of the reason is because it's also not glamorous. Nobody talks about how great a piece of software's documentation is (though I'll bet without solid documentation people rarely would describe any software as that great).
Part of giving documentation visibility is also not over-emphasizing the code. While it's easy and tempting to make your 'contributors' page a list of commits to your version control, think: does this include the people who helped with testing, or documentation, or bug scrubbing? Try to keep these things in mind when you're building your 'community' and the pages that represent it.
Taking action
So how can this be combatted? I suggest dedicating someone to this task. Acknowledge that it takes time and effort and that you consider this to be important. Make documentation of paramount importance. It will never 'organically' happen. It will take a conscious effort.
Additionally, if you are doing open source give the most positive feedback to people helping with this area of your project. Put up the fewest barriers to them. Your docs likely don't need the same stringent rules before acceptance that perhaps your code does. Maybe your one person in charge is authorized to scrub and accept all documentation updates. Positive feedback and a great experience are two important ways to keep people engaged and willing to contribute.
Find ways to acknowledge those who contribute in this way. Afford them the same status as anyone contributing code.
Getting started
Looking for some place to start? I have a suggestion: documentation-driven-development. If it's not documented, it doesn't exist. This isn't a new thing it's the reality that already exists. If a person doesn't know how to use something in your software they can't use it. Following this train of thought, make everything follow your documentation. Integration tests now become documentation tests, they test what your documentation says is how things work. This is by no means the only way to do it, but it is a great place to start if you need one.
You won't be going alone
I've tried to find a few good examples of projects that are giving the people who help w/ documentation credit, and I know there are many others.
On the Ampersand contributors page, everyone is given equal representation whether they contributed readme updates, css tweaks, or actual code. In fact I would like to take the opportunity to call out @remko for creating an Ampersand dash docset that I use every day.
Drupal has a whole page/subcommunity dedicated to helping with documentation.
Django puts documentation on the same level as code, and lists several people on their committers page as having documentation be their main area.
Another good example is Symfony which has a specific area where people who helped with documentation are acknowledged.
Do you know of projects that are doing documentation right? Shout their praises to me on Twitter.
p.s. I am focusing on one facet of software but there are many, this post is intended as a focus on one of them not a distraction from others such as QA, support, bug scrubbing, education, ops, (I could go on), all of which are just as important as the rest. The incorrect primacy we give developers in the software ecosystem is unwarranted and harmful to your own projects. Let's work to change that.
Want more like this (and also get a bi-weekly dispatch of stuff we're learning and doing at &yet?) Join our community! We can't be &yet without &you.