Subscribe to Documentation Team feed
News and discussions about Drupal documentation
Updated: 12 min 5 sec ago

Help us write a new Contributor Guide

Mon, 2020/06/15 - 1:16am

How did you first get involved with contributing to the Drupal project? If you're like me, it was at a DrupalCon contribution day, where a wonderful mentor guided me through the pitfalls of joining in to our global project. But not everyone has the chance to attend a DrupalCon or other event with mentors, so many people instead try to navigate through the "Getting Involved Guide" on drupal.org to figure out how they can contribute. Unfortunately, it is not our best collection of documentation -- it is hard to navigate in order to find either a quick task to do to get started contributing, or a longer-lasting role to fit into.

So, some of us have been thinking for a while about how to make use of Drupal to provide a better Contributor Guide. Over the past few months, we created some new content types and views for drupal.org, and they just got deployed.

And that's where you come in: it's time to write the content for this new section! There are two tasks that are currently ready for you to work on, and you can do each of them several times.

Write content for Skill pages

I've made starter pages for the "Skills" pages for the new Contributor Guide (see link above for a description of the content types), and they all need content and editing. To work on this task:

  1. Find a skill page to edit here: https://www.drupal.org/community/contributor-guide/use-or-improve-your-s... -- scan down the list for ones that have "needs details" in their summary lines.
  2. Click the title to go to the skill page you want to edit
  3. Click Edit, and edit the page (you'll need to be logged in). Follow these guidelines:
    -- Leave the title as it is -- if it needs adjustment, discuss in Slack in #documentation
    -- Remove the "needs details" from the summary line so that we'll know it doesn't still need details
    -- If you have questions, or want someone to review what you wrote, post a message in Slack in #documentation ; if you don't use Slack, you can post a comment here to get help (but it might take a few days).
Create new Task pages from existing Contributor Task pages

The other thing that we can start doing now is creating new Task pages. We have some existing pages in the Getting Involved Guide that describe tasks, and migrating these to the new format should be fairly straightforward (I hope!). To help with this effort:

  1. Find an existing task page under https://www.drupal.org/contributor-tasks
  2. Make sure that the task doesn't already exist on https://www.drupal.org/community/contributor-guide/find-a-task
  3. Go to https://www.drupal.org/community/contributor-guide/background-and-refere... to read about the new content types and find out how to create a Task
  4. Copy and/or adapt the text from the old source page to make a new Task
  5. We will eventually want to delete the old task page and redirect to the new page. So, post a comment on this issue to ask for that to be done (include the old/new URLs of the source/new page): https://www.drupal.org/project/drupal_org_community/issues/3138007

Help finish up the Help Topics!

Fri, 2020/04/17 - 10:57pm

I've made a few posts here in the Documentation group on groups.drupal.org over the past few years about the Help Topics experimental module. Today, I have a very brief update on the project, and a call for help in editing/reviewing the topics for the new Help Topics system!

Status update: The Help Topics module has achieved "Beta test" status, which means that when you download Drupal 8.x or 9.x, the module is included in the "Experimental" section. We are working towards getting it to "Stable" status, so that it can move out of the Experimental section; the plan is to merge it into the existing core Help module, so that people installing Drupal with the Standard profile will get the new Help Topics by default.

Call for help: One of the things we need to do to get Help Topics to Stable status is to finish writing help topics covering all of the Drupal core modules. We are well on our way to having that done... The main need right now is for people to review the topics that have been written. Here are the steps:

  1. You need to be logged in to drupal.org, and I recommend using a desktop or laptop sized browser. You'll need some knowledge of how to use the Drupal administrative interface, as these instructions are not too detailed. Also this doesn't go into much detail about how to use issues in the Drupal project. But you don't need to know any programming! We're looking for review of the text of the topics here.

  2. Go to the "Meta" issue that lists all of the issues about writing new help topics:
    https://www.drupal.org/project/drupal/issues/3041924

  3. Look in the sidebar of the page for an issue whose status is Needs Review and whose issue title is something like "Convert ___, ___, ___ module hook_help() to topics". If you can see colors, status Needs Review issues have a yellow background; you can also hover your mouse over an issue link and see the status.

  4. Click the link to open the issue.

  5. Locate the latest "patch" file on the issue, which should be shown at the bottom of the issue summary, just before the Comments section starts. Copy the link to the patch file into your clipboard.

  6. In a new browser tab or window, go to https://simplytest.me/ and create a new Drupal testing site with the following parameters:

- Project name -- Drupal core
- Version -- 8.9 or 9.0 branch (branches are listed at the bottom of the version list)
- Advanced options > Add a patch -- paste in the link to the patch file from your clipboard

Once those parameters are set, click "Launch sandbox" and wait for the site to be created.

  1. Log in to the site with user name "admin" and password "admin" (which is standard for simplytest.me sites).

  2. Go to admin/modules and turn on the experimental Help Topics module, plus all of the modules for the help topics issue you are reviewing (they should be listed in the issue title by short name).

  3. Go to admin/help and review the topics. There are instructions in the issue summary about what to look for in the review (under Remaining Tasks in the issue summary). To figure out what topics are being created or modified in the issue, click the link for the patch file and look for lines that look like this:

    +++ b/core/modules/help_topics/help_topics/breakpoint.overview.html.twig
    @@ -0,0 +1,21 @@
    +---
    +label: 'Managing height, width, and resolution breakpoints'
    That means that if you go to
    admin/help/topic/breakpoint.overview
    in your test site, you should see the topic.
  4. Add a comment to the issue about what you found in your review. If you found problems, set the issue status to Needs Work. If it all looked good, set it to Reviewed and Tested by the Community.

Thanks!!