Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
103 lines (81 sloc) 5.27 KB

Contributing to DX Knowledge Base

We welcome contributions to our open source project on Github.

Issues

Feel free to submit issues and enhancement requests.

Contributing

Please refer to each project's style and contribution guidelines for submitting patches and additions. In general, we follow the "fork-and-pull" Git workflow.

Follow these steps:

  1. Fork the repo on GitHub
  2. Clone the project to your own machine
  3. Commit changes to your own branch
  4. Push your work back up to your fork
  5. Submit a Pull Request so that we can review your changes

NOTE: Ensure that you merge the latest changes from "upstream" before making a pull request.

Feeling and Grammar

  • Use active voice whenever possible
  • Establish a clear structure and try to be precise
  • Be brief, clear, and direct
    • Important information in the main clause
  • Simplify your language
    • Use fewer words and get to the point
  • Avoid jargon and abbreviations
    • Define acronyms and initialism on their first use - give the abbreviation in parentheses after the full terminology
  • Use a grammar check tool, for example:

Source: How to Become a Technical Writer: A Beginner’s Guide

Content Composition

Repository Folders

  • There are 3 important folders in the root of the repository:
    • files - stores all the images and other files necessary for articles (problem/practice)
    • problems - stores all DX problems
    • practices - stores all DX practices

File Format

Content Format

Example article: pull request (raw)

  • meta informations
    • starting with --- (a triple dash) and ending with a second --- (triple dash)
    • contains meta info of the article
    • slug - friendly ID of the article visible in the URL of the Knowledge base (e.g.: https://developerexperience.io/practices/pull-requests
    • aspect - Categorizes the article to some aspect of the development process. Valid values are:
      • architecture
      • processes
      • tooling
      • culture
    • stages - Categorizes the article to some stages of the project. Valid values are:
      • research
      • building_team
      • development
      • launch
      • maintenance
      • phase_out
    • short_description - description of the article used for SEO
      • max. 250 characters long
    • tags
      • visible to use in the Article's detail
      • used to connect problems and practices with other similar areas than aspect or stage
      • each tag has it's own detail (e.g. tag design)
      • amount of tags for the article is not limited
    • keywords
      • invisible in the KB
      • used for SEO
      • max. 10 keywords
  • markdown content
    • everything behind the second --- (triple dash)
    • headlines
      • first H1 is recognized as the name of the article
      • We want to keep similar structure of all articles informing about the practice or problem. So we require to keep only few specific H2 headings:
        • What Is a %{name}
        • Why You Might Want the %{name}
        • Problems the %{name} Helps to Solve
        • How to Implement the %{name}?
        • Common Pitfalls of the %{name}
        • Resources for the %{name}
      • Follow the "The Chicago Manual of Style" to capitalize your titles
        • You can use this tool for the title capitalization: Capitaize My Title. Write your title and select "Chicago".

Copyright and Licensing

The DX Knowledge Base open source project is licensed under the Attribution-NonCommercial-ShareAlike 4.0 International License.

FAQ

You can’t perform that action at this time.