Contributing to Apigee's Drupal module documentation

Contributions to the Apigee Drupal module documentation guides are welcome and appreciated. Before getting started, please read through the suggested methods for contributing and the associated style guidelines.

How can I contribute?

Members of the Drupal and Apigee communities are welcomed and encouraged to contribute to all types of Apigee module documentation. This includes writing and sharing:

• Snippets for common customizations
• Troubleshooting tips and tricks
• Related blog posts
• Suggestions for documentation updates or expansion.

The documentation for Apigee modules can be found in the following locations:

• Drupal module project pages
• Drupal module GitHub READMEs
• Drupal documentation guides and pages

The methods for contributing to these docs are described in greater detail in the following sections.

For Apigee Drupal module maintainers

If you are an Apigee Drupal module maintainer and you would like to add, update, or remove documentation, you can:

• Edit a Drupal documentation page directly on Drupal.org
• Create an issue in the appropriate GitHub issue queue for the module
• Submit a pull request against the GitHub README with suggested edits.

If you would like to edit an existing page on Drupal.org:

1. Review the writing style tips below.
2. Log into your Drupal.org dashboard.
3. From the page you would like to edit, click the green Edit button.
4. Make updates as needed in the Body section of the node. You can use the WYSIWYG or plain text editor.
5. Please enter a brief description of your changes in the Explain your changes section of the node.
6. Click the Preview button if you wish to preview your changes before publishing.
7. Click the Save button to save and publish your changes.

If you would like to add a new page or doc guide on Drupal.org:

1. Review the writing style tips below.
2. Draft your content as desired, including:
   • A proposed title.
   • A proposed location in the Documentation guide table of contents.
   • Any image files or assets required.
3. Open an issue in the relevant Aigee Drupal module Github Queue as a Feature request.
4. Assign the Documentation label to the issue.
5. Either enter the suggested doc text, or attach your draft content file to the issue.
6. Click Submit new issue.

Do NOT add a new page, update a page title, or adjust a module’s Documentation Guide table of contents in Drupal.org. This can result in broken links and 404s throughout the doc ecosystem. For more information, contact jennbbennett.

For Apigee Drupal community members

If you are a member of the Apigee Drupal community and you would like to add, update, or remove documentation, you can:

• Create an issue in the appropriate GitHub issue queue for the module
• Submit a pull request against the GitHub README with suggested edits.

If you would like to add a new page, or suggest updates to an existing page on Drupal.org:

1. Review the writing style tips below.
2. Draft your content as desired, including:
   • A proposed title.
   • A proposed location in the Documentation guide table of contents.
   • Any image files or assets required.
3. Open an issue in the relevant Aigee Drupal module Github Queue as a Feature request.
4. Assign the Documentation label to the issue.
5. Either enter the suggested doc text, or attach your draft content file to the issue.
6. Click Submit new issue.

Writing style guidelines

Our goal is make our Apigee module documentation clear and understandable. To do this, we rely on the highlights and general principles of the Google Developer style guide and the Drupal.org content style guide.

Before drafting content to add to or update the Apigee Drupal module documentation, we suggest that you review the resources noted above. For your reference, a quick summary of important principles is provided below.

Recommended tone and content

• DO use a friendly and helpful tone.
• DO aim for sentences that are clear, simple, and concise.
• DO write for a global audience. Try to avoid using idioms, slang, or humor that may not be understood by those outside your geographic region.
• DO try to avoid the use of industry jargon or buzzwords. Keep your language accessible to all users, including those new to the technology.
• DO NOT use phrases like simply, It's that simple, It's easy, or quickly in a procedure.
• DO NOT use “please.” Use polite, clear language instead.

Time-sensitive language

• DO NOT use “now” or “currently” or “new” to refer to a feature set or documentation addition. Avoiding time-sensitive language minimizes doc maintenance in the future.
• DO NOT announce a planned feature or describe a feature as “coming soon” unless your docs include a product roadmap. If possible, avoid making promises or giving hints about future developments.

Grammar and word choice

• DO use the present tense if at all possible.
    Ex: Use “This command starts the service” instead of “This command will start the service.”
• DO use an active voice to clarify who is performing the action.
    Ex. Use “You can document your APIs with Apigee API Catalog” instead of “The APIs can be documented using Apigee API Catalog.”
• DO use “you” instead of “we” to address your reader, to avoid confusion as to the intended audience or actor.
    Ex. Use “You can build a developer portal by...” instead of “We’ll create a developer portal by…”
• DO use standard American spelling and punctuation
• DO try to avoid starting all sentences with the same phrase (such as You can or To do).

Localization

• DO use unambiguous date formatting. This can be dates in full, or ISO date format.
  • Ex: January 12, 2015
  • Ex: yyyy-mm-dd

Formatting

• DO use numbered lists for sequenced steps. For all other lists, use bulleted lists.
• DO precede lists with an introductory sentence or phrase ending in a colon.
     Ex: With API Catalog, you can:
  • Add a new API doc.
  • Edit an API doc.
  • Add an image and description to an API doc.
• DO consider tables for organizing and comparing items with similar attributes or multiple parameters.
• DO use serial commas.
• DO use bold text for UI elements including:
  • Menu items
  • Tab headings
  • Buttons
  • Icons
• DO put code related items in code font.
• DO Use sentence case for headings. Only capitalize the first word of the heading, except for proper nouns or acronyms.
• When using acronyms, make sure that the first use of the term is spelled out, with the acronym to follow.
• DO use only one space after a period.

Use of images

• DO use SVG files or PNG images where possible.
• DO check for image responsiveness and size on various screens.
• DO add alt text to image tags to improve content for accessibility.

Product Naming reference

• Apigee Edge module
• Apigee API Catalog module
• Apigee Monetization module
• Apigee Kickstart distribution
• Apigee Edge UI (or Edge UI)
• Apigee Edge APIs (or Edge APIs)
• Apigee hybrid

Links and formatting

• Link text should be descriptive. If linking to another section, header or page, use the section, header or page title as your link text., if possible.
• Add class=”external” for links pointing to references outside of Drupal.org.
  • If referring to external documentation, mention the organization responsible for the documentation.
  • Adding target=”_blank” is not necessary. Allow the user to decide whether or not to target a new page when opening a link.