Contribute Your Hell

Engineering Hell was never meant to be written by one person. We all have expirenced some form of hell in our careers and we all have a story to tell. If you would like to contribute to Engineering Hell, please follow the guidelines below.

Qualifying Stories​

First, let's start with what is a qualifying story. A qualifying story is a story that is about a hellish expirence you had in your career. This could be a project that went wrong, a boss that was a nightmare, a coworker that was impossible to work with, or any other expirence that made you question your career choice. The story should be about a specific expirence and have some learnings to share to help others avoid the same fate.

How to Contribute​

To contribute to Engineering Hell, it just takes a pull request on GitHub! please follow these steps:

1. Fork our github repository: https://github.com/parabuzzle/engineeringhell
2. Add yourself to the authors list in the blog/authors.yml file if you are not already there.
3. Create a new markdown file in the wip/ directory. The file should be named with the following format: title-of-your-story.md
4. Add the proper frontmatter to the beginning of your file (see below)
5. Create a pull request with your new file.

We will review your pull request and provide feedback if needed. Once your story is approved, we will move it to the blog/ directory and publish it on the site.

Frontmatter​

The frontmatter of your markdown file should look like this:

---
title: Your Story Title
description: A brief description of your story.
authors: your-author-tag (from blog/authors.yml)
tags:
  - hardware (from blog/tags.yml)
  - ...
---

The title field should be the title of your story. The description field should be a brief description of your story. The authors field should be your author tag from the authors.yml file. The tags field should be a list of tags that describe your story. You can find the list of tags in the tags.yml file.

We will add the slug field for you when we move your story to the blog/ directory.

Markdown and Docusaurus​

We use Docuasurus to build our site. If you are not familiar with Docusaurus, you can find more information here. You can also look at the markdown files in the blog/ directory for examples of how to format your story.

There is a markdown specific guide for Docusaurus here.

Images and Graphics​

We encourage you to make your story visually appealing with images and graphics. You can add images to your story by placing them in the static/img/blog directory and linking to them in your markdown file. You can also use graphics tools like Mermaid to create charts and diagrams for your story.

Do's and Don'ts​

Do​

• Do provide a detailed account of your expirence.
• Do share the learnings you took away from the expirence to help others.
• Do use images and graphics to make your story visually appealing.
• Do follow the markdown and frontmatter guidelines.
• Do share your story with the community.

Don't​

• Don't share any confidential or proprietary information.
• Don't share any personal information about others without their consent.
• Don't use any copyrighted images or graphics without permission.
• Don't use any offensive language or content.

Questions?​

If you have any questions about contributing, please reach out to Mike on Bluesky or on GitHub issues.