Come together with the global Drupal community in Rotterdam, 28 Sept – 1 Oct 2026. Sessions, contribution, connection, and Early Bird savings until 8 June.Develop/edit content for the Contribute to Documentation page.
https://www.drupal.org/community/contributor-guide/contribution-areas/do...
Tasks
For these tasks, see the following guidelines pages:
Also, add comments to this issue when you do any of these tasks, explaining what you did. Tasks:
- [Done]
Take content from the existing section on /community if there is one, and if not, give a similar overview of what happens in this contribution area. Put it into a new page under Contribution Areas. - [Done]
Follow the steps in the Guidelines for contribution areas to get it set up properly (taxonomy term, blocks, etc.). - [Done]
Add (or migrate from the old Getting Involved Guide) related Contributor Tasks. A Task has a well-defined goal and well-defined steps. - Add (or migrate from the old Getting Involved Guide) related Contributor Roles. (See also #3091381: Create a list of all roles, skills, responsibilities in the drupal community) A Role is a "position" in the community (short- or long-term).
Status: We have some roles. Roles still (probably) needed:- Documentation Editor. Note that we have a role now called Technical Writer. We should have a different one for editing and proofreading, and we should reference the new "Edit an existing documentation page" task.
- Documentation guide maintainer
- Add (or migrate from the old Getting Involved Guide) related Contributor Skills. A Skill gives you the knowledge to perform a Task or fill a role.
Status: We have some skills. Skills still (maybe) needed:- Proofreading (as distinct from editing and tech writing)
- [Done]
Add (or migrate from the old Getting Involved Guide) Contributor Reference Information: Background and reference information that is common to more than one Contributor Task. - [Done]
Add Contacts section to the page. - [Not applicable]
Revise existing /community section to reduce to mostly being a link to this new landing page.
Comments
Comment #2
chicagomom commentedComment #3
chicagomom commentedComment #4
jhodgdonComment #5
jhodgdonComment #6
jhodgdonStandardizing issue summary.
Comment #7
jhodgdonbetter title
Comment #8
jhodgdonI migrated two of the tasks related to documentation:
https://www.drupal.org/community/contributor-guide/task/triage-a-documen...
https://www.drupal.org/community/contributor-guide/task/resolve-a-docume...
Tasks I'm not sure about whether we should migrate or not:
a) Add keywords to a doc page: https://www.drupal.org/contributor-tasks/add-keywords -- note that someone already migrated this but it's marked as "Do not use yet" https://www.drupal.org/community/contributor-guide/task/add-keywords-to-...
The problem with this task as it is: the Keywords field only applies to old Book content type pages.
We do have a Tags field on the new doc guide/doc page content types. So we could edit the task so it is about adding tags... but I am not sure tags are useful in any way (you can't search by tag as far as I know), so I'm not sure if we want to encourage people to add them to docs pages?
b) https://www.drupal.org/contributor-tasks/fix-page-titles -- fixing page titles -- the standards are up in the air on that one, see #3142880: SEO / UX - add sub guide title to title tag to avoid duplication
c) https://www.drupal.org/project/drupalorg/issues/3142880 -- incorporating comments -- I think this one is difficult to write up a task about. The problem is we used to be able to search for pages with comments and know they should be incorporated. But the current content types add a comment whenever there is a page update, so pages with comments are not necessarily having things to be incorporated. Also there are guide maintainers, so they get notified if there is a comment... I think we should probably just delete this task?
d) The task about editing a docs page https://www.drupal.org/contributor-tasks/edit-documentation-page references the obsolete Docs Management Page. See #2989810: Make it clear how to report docs issues and find pages that need attention
Any thoughts?
Comment #9
eojthebraveComing here from the discussion in Slack ...
In general, I've found tasks like "Edit titles" and "Add keywords" to be somewhat challenging for anyone but the most experienced documentation contributors. And I don't think they're as easy as they might seem on the surface. It can be really challenging to figure out which pages need updates vs. which were updated by someone else doing the same task a few days ago, etc. They might work better if we had some kind of running list of pages to review but that's maybe outside the scope of this particular issue.
a.) Regarding keywords and tags. I don't think they're that useful honestly. I've never personally gotten much out of them. And I've never used the taxonomy to browse documentation. Maybe others have? I think if you're going to review keywords making sure that they are in the text of the page so Google can find them is likely more useful. Also, I'm not convinced that adding tags from an unlimited set of possible tags is all that useful either. In order to be useful I think tagging to needs to use a limited set with a bit more management in place for what each tag means. As is, there's a huge mess of tags and no consistency.
In my experience trying to mentor people doing these tasks they spend way more time trying to find a page that needs an edit than making edits. And it's discouraging.
We could pair down the list of tags, and make a task about reviewing existing content more rigorously applying them ...
But I think until we can make the case for why this is a useful task to do, and prove that it's providing value, it's kind of make work, and for now we shouldn't worry about migrating it.
b.) The edit titles task could be a good one, but I wouldn't want people to work on it until we sort out the related issue. After that though it's a good example of a thing where we could come up with a list of every page and then let people choose sub-set of the list to start working on. Making it clear which pages have already been updated and which have not.
c.) As for comments, yeah ... they're not really used in the same way as they were when that task was originally created. And were moved to a secondary tab in order to hopefully encourage people to update the content rather than leave a comment. Previously we found that people were less willing to update the content if they could just leave a comment with their changes. I honestly haven't reviewed enough comments recently to say if the ones that are coming in are worth rolling into the content or not. I'm in favor of deleting this task. And maybe in it's place encouraging people to become guide maintainers or co-maintainers.
d.) I do think we should migrate/update this page. And perhaps roll the content about adding keywords, and editing titles, into it? But I also think this suffers from the "Okay great, but which one should I edit?" problem.
Comment #10
jhodgdonGreat! I think we're in agreement here. For now, I will go ahead and delete the tasks that are questionable, since I don't think we want them, and redirect them to the Contribute to Documentation page (which will automagically list all the tasks that are linked to the Documentation contribution area).
For (d), we are working on this related issue. Once we figure that out, we can migrate the task and point people to the view that will be created in that issue.
Comment #11
jhodgdonAdding some suggestions for tasks, roles, skills from #3138007: Create content for the identified roles, skills, and tasks. Also updating status.
Comment #12
jhodgdonI added two new roles. This issue is now complete.
https://www.drupal.org/community/contributor-guide/role/documentation-ed...
https://www.drupal.org/community/contributor-guide/role/documentation-gu...