Contributing to documentation FAQ
Updating and maintaining Drupal's documentation is a big task. For a new contributor, learning how how to contribute to the documentation can have a bit of a learning curve and often lots of questions arise in the process. This page attempts to provide an overview of those questions, with very brief answers and links to more information.
As you can see, this page is currently itself a work in progress. ;) You are, naturally, encouraged to contribute.
I just want to suggest a one-off change and I'm not interested in joining the docs team. How do I do that?
If you don't yet have an account on Drupal.org, create one. Then you can do one of several things, depending on your comfort: edit the page directly using the "Edit" tab (unless it is a locked page), create a new issue (which is like a ticket) in the Documentation project or leave a comment on the page itself. If you are trying to change API documentation, see "How do I change the API documentation?", below.
I'd like to contribute to documentation. How do I get involved?
There are several quick and simple ways you can help improve documentation, without joining the documentation team.
I've submitted a few issues about documentation and/or created a few handbook pages, but I'd like to do more. What's next?
If you'd like to do more than the tasks above, you can join the documentation team. This will allow you work on many locked pages and have access to the format to add images and tables to pages.
Once you have joined the docs team, you can continue contributing simply by making more improvements.We have a list of simple tasks you can get started on.
Beyond that, keep thinking of new handbook pages you believe need writing, and then begin to write them yourself. You can also monitor the documentation issue queue to find things that need doing, and then fix some of the issues other people reported.
I'm a new member of the documentation team and am eager to help out. What sort of things do I need to know?
As you edit others' work and add new work of your own, be sure to keep the Handbook style guide in mind and follow what it says. Others who are doing the same thing as you will eventually find your page and try to bring it in line with the style guide, anyway.
Additionally, we recommend that to involve yourself further you should join and monitor the documentation mailing list, where discussion of documentation strategy and direction takes place. However, before bringing up a new topic in the documentation mailing list, please be sure to search through the mailing list archives so that you will be on the same page as everyone else is and so that we don't rehash old topics that have already been decided upon.
You may also consider reading the rest of this FAQ, of course.
For a much bigger overview of contributing to Drupal's documentation, see also:
- About Drupal documentation
- Contributing to documentation
- Documentation writer's guide
- Introduction to the issue queue
I found a page that is completely out of date, or redundant. How do I remove it?
If you are not a member of the documentation team and you find a page that is no longer useful or that you believe should be removed for any other reason, you should submit a new Documentation project issue so someone from the docs team can review it. If you're unsure of how to use the issue tracking pages, see "I am creating an issue about X thing. Which project/component/category should I set it to?", below.
If you are a member of the documentation team, then you should follow the instructions regarding outdated pages on the Documentation writer's guide.
What are all these references to "d.o" and "a.d.o" that I am seeing all over the place?
These are shorthand references to "drupal.org" and "api.drupal.org", respectively.
Some documentation isn't in handbook pages -- where is it?
Some kinds of documentation are kept in other locations:
- The API documentation for Drupal developers is auto-generated from files in CVS. To update the description of a file or function, submit a doxygen patch against the core file in question.
- To update one of the "topics" pages, hooks documentation, or pages such as the Forms API reference, see Updating API documentation.
- Embedded documentation is included with every Drupal installation.
How do I change the API documentation?
To change the API documentation, you need to submit a code patch because the api.drupal.org site uses a special module (the api module) to parse the Drupal source code itself and produces the HTML output from the Doxygen comments in the code. However, the parser actually looks in two different places to produce the full documentation, depending on which API documentation page is being requested.
Things like format_interval(), and variable_set() have documentation in core, but hook_nodeapi for example won't be in core, because there is no 'hook' module in core to implement them (that is, the 'hook' is just a placeholder). So instead, there is reserved space in the contrib CVS repo that has extra documentation for these so-called "phantom" functions. The api.drupal.org site parses either the code in the core repository or the code in the contrib repository depending on where the API documentation is actually coming from.
What this means is that if you want to change the API documentation, then you'll either need to patch core if that's where the content is coming from or you'll need to patch the docs in the contrib repository. If you want to patch core, you should create an issue for the Drupal project, and the Documentation component. If you want to patch the docs contrib repo, create an issue for the Documentation Project, with the Documentation in CVS component.
See also: