Skip to content

Latest commit

 

History

History
73 lines (38 loc) · 3.76 KB

general-contribution-guideline.md

File metadata and controls

73 lines (38 loc) · 3.76 KB

Contribution Guidelines (general)

This guide describes the process and the conventions for contributing an article without relaying too much on GitHub. For detailed instructions on how to contribute using GitHub, please refer to the GitHub Contribution Guidelines.

Announce

  1. Check for Duplicates: Is there already an article about your topic?

    • Please check our Backlog of Articles whether there is already an article existing or planned for similar topic. You need a GitHub account for this.

    • If there is already a similar article, you can contact the author and find a solution (leave the subject to the author, offer your help as reviewer or co-author, take the subject over, or write a second article in response or extension to the first article, ...).

  2. Announce an Article:

Discuss

It proved to be useful to discuss about an articles content before writing the article. Ask your colleagues, maybe they have some valuable input!

To discuss about an articles content, you have various options:

  • Use the Issues on Github: discuss directly in the issue you created - and don't miss to give feedback to other announced articles.

  • Use Yammer, a coffee break, a team event or similar

Write

Content Conventions:

  • short enough to be read in 10 minutes: size should be less than 2 A4 pages long in printout PDF version (that is between 400 and 750 words)

  • reflects on a single subject only (better make several articles, if you have too much material / ideas to write about)

  • matches our Vision: it is about practicaly proven concepts, best practices, cultural philosophies or great ideas that we use in our daily work at Zühlke.

  • the subject is related to our work and the advice concrete enough to consider.

  • the subject is something you have experience on in some real projects and not just theoretical ideas

Structural Conventions:

Language Conventions:

  • written in UK English (see advanced contribution topics for information about a translation)

  • Titles are written in sentence case (i.e. lower case for all words apart from the first one)

Formal Conventions:

  • Textfile with the file extension *.md

  • Formatted using the Markdown Syntax

The Example Article is a good starting point.

Peer Review

Before you publish your article, make sure you get your article reviewed by at least one collegue. To get it reviewed, you have the following options:

  • Use a Github Pull request and its reviewing features (see GitHub Contribution Guidelines)
  • Ask on Yammer for (a) reviewer
  • Share your article using Office 365, Email, whatever suits you

Lead Author Review

As soon as your article is reviewed and ready to be published, you can send it to a Lead Author or use a pull request on Github as described in GitHub Contribution Guidelines

Please note that we are using a public repository - everything you publish/commit can be read by everyone.