Contributing to Documentation

This page highlights the process for contributing to the Varbase documentation as well as some writing tips and guidelines.

Screenshots Guidelines

  • Take screenshots from the latest version of Varbase.

  • For consistency use this screen resolution when taking a screenshot: 1366 x 768. You can use the Window Resizer Chrome Extension to help you set the window size.

  • Use Awesomescreenshot to help you out.

    • Only use the visible part option, no need to take the whole page, and crop it.

    • Use annotations (Arrows, Steps numbers, Highlights, Rectangles ...etc.) to annotate the screenshot. Always use the red color.

  • Make sure screenshots are displayed in a good resolution, not pixilated.

  • Always add a caption to screenshots or images in the documentation page. Captions must be following APA title case style. Use capitalizemytitle.com for help.

  • Take screenshots from real content on Varbase website and not from other sites.

Writing Style

Naming Standards and Capitalization

  • Always capitalize the word Varbase when mentioning it.

  • Use Grammarly to check on proper grammar and punctuation.

  • All titles (H1, H2, H3) must use APA title case style. Use capitalizemytitle.com for help.

  • All modules and component names must use APA title case style.

Headings

  • All titles (H1, H2, H3) must use APA title case style. Use capitalizemytitle.com for help.

  • Use descriptive headings and titles because they help a user navigate their browser and the page. It's easier to jump between pages and sections of a page if the headings and titles are unique.

  • When possible, use -ing verb form in title to indicate present participle or gerund. Example: "Managing Menu Items"

Text Styling

  • Whenever a module or component name is mentioned, it should be bold. Example: Varbase uses the Layout Builder module.

  • Divide each documentation page with hierarchical titles starting with H1, then H2, then H3. This will reflect in the "CONTENTS" side bar.

  • When explaining a path to the user, use bold trail of links separated by backslash (\) making the last item (where the user should land) in italics. Example: Navigate to Administration \ Configuration \ Search and metadata \ Metatag.

  • When a line of code or command is needed, highlight the text and use <> option from the tooltip. Example: cd /path/to/webserver_directory

  • To make your documentation nice to read, you can add blocks of hints and notes with nice icons by clicking on it, then change it to the desired one. Example:

See Platform.sh documentation on developing with Drupal and Varbase as an example. See https://docs.platform.sh/frameworks/drupal8/developing-with-drupal.html

Last updated