Skip to content

Latest commit

 

History

History
271 lines (181 loc) · 23.9 KB

CONTRIBUTING.md

File metadata and controls

271 lines (181 loc) · 23.9 KB

Contribution Guidelines

Welcome to Section’s Engineering Education program. This program is dedicated to creating a community that provides students/contributors a friendly and inviting place to contribute to, build up their skills, while growing their professional portfolios/profiles (upon entering the DEV career space).

  • Students can contribute content, blogs, articles, tutorials, video, audio, or code contributions, and of course ideas via discussion to the EngEd community.

All articles and blogs are published and added to the EngEd generated pool of educational content that is useful for engineers of every level.

We’d recommend reviewing our most recently published content here to get a sense of:

  • Article structures and format.
  • Quality of articles we are looking for.
  • Type of content that has been contributed (to help avoid topic overlap).
  • Topics you can begin working on.
  • Find topics you'd like to build or expand upon.

Articles do not need to be Section-specific or strongly Section-related. This is not necessarily about Section or Edge Compute directly, but rather an effort to provide educational value to software developers within the diverse ecosystem of web technologies.

We are looking to create a pool of content that will be unique from what is already readily available (through the official docs & other blog sites).

We need to be sure that any incoming content is providing unique value that addresses a specific use case or challenge that developers face.

Articles should be a minimum of 750 words.

In order to participate in the program, all members will be required to agree to established terms and conditions. (Agreement is included as part of the enrollment process.)

In order to achieve a level of consistent style and increasingly elevated quality, we have created this document to help new contributors. Let's start by reviewing what's needed.

NOTE: (Please ensure to only have ONE open issue + linked pull request at a time. This will ensure a steady output of EngEd articles and that they are completed in a timely manner from inception to publishing).

Requirements for New Contributors

  • GitHub account (Please be sure to have a basic understanding of GitHub and Gitflows. Eg: Pull requests, commits, merge, etc.
  • Text editor, such as Visual Studio Code, Sublime Text, Atom
  • Prepared Markdown (.md) file. (Note: All articles must be submitted in properly-formatted Markdown.)
  • To ensure expedite reviews, publishing, and payouts for articles, we request that all first drafts submitted be error-free (pre-checked for English grammar, technically accurate, properly cited, formatted, etc.) and it be ready for publishing by meeting our suggested article guidelines as outlined below.

Here is a free tool to help improve your writing skills. Please be sure to go over our resources page to take a look at all the listed resources to help improve overall techinical writing abilities.)

All contributors are expected to review and adhere to Our Code of Conduct before submitting articles.

Suggesting a topic

Be sure to search for similar ideas in our published articles and #eng-ed-topics channel in Slack to help avoid overlap, ensuring that you are bringing a unique viewpoint to your suggested topic. If there are related articles that have been published, have a think about how you can build off those to bring additional value that hasn’t already been presented.

Once you have narrowed your topic search to one you would like to write about, fill out the EngEd Content Idea Suggestion form with your article suggestion. This will help you to think through and frame your content, while giving us a better idea of the key takeaways that you intend to communicate to your audience.

Below is an example article and some suggested templates to help get you started:

Once your topic has been approved and you have a final draft of your article ready to submit, follow these step-by-step instructions.The instructions walk through how to submit a PR (pull request) in Github with your fully prepared article.

Submitting your article

Only submit or create a PR (pull request) when your draft is completely polished and publish ready, (that is, the article could be published as is - take in mind this is an opportunity to create a presence in the larger developer community and your work may be seen by future potential employers).

Once again you can follow these step-by-step instructions once your article is ready to be published.

The instructions walk through how to submit a PR in GitHub with your fully prepared article.

Ensure all article submissions are pre-checked for English grammar, technically accurate, and delivered under the assertion that the content is original to you and includes proper citations (including sourced images) and has not been published somewhere else.

Before submitting your article, we request that you cross-check the readability of your content using this free tool. This check helps make your writing BOLD & CLEAR by calling attention to any lengthy, complex sentences and common errors. If you see a yellow sentence, you may want to shorten or split it.

Before submitting your article, we request that you place your article through a 3rd party plagiarism checker?

We suggest using Quetext this is a free tool and has a daily limit.

We typically accept articles with 10% (plagiarism report %) or less.

These guidelines are intended to help EngEd contributors grow as authors and to enrich the larger engineering community as a whole by continuing to create higher quality educational articles, tutorials, how-to’s,technology reviews, etc.

Communicating your key takeaways

Articles should be clear, accurate, and fully explained. We are more interested in substance than length, and supporting examples are always encouraged. At the same time, articles that include mostly code with very little narrative lack sufficient depth and guidance for the audience to fully grasp important concepts.

We suggest you think about what is most important to your article or any pain point you are addressing. Assume the audience is smart but has no prior exposure to the common terminology in your article.

For example:
If your article is about serving ML models with Django, then the reader should have a decent understanding of something like: 

1) The structure of a django app
2) How to use such an app to serve a model for inference

The details your article gives should help further grow the readers’ skills as they practice on their own projects.

EngEd Community Contribution Initiative

One of our primary goals for the EngEd community is to provide students/contributors a friendly and inviting place to contribute to real-world projects to help students build up their professional portfolios and profiles (upon entering the DEV career space).

We have created a process for the EngEd community to suggest, contribute, add, and build features for the EngEd community. By allowing the community to build the features/enhancements they want to see in the EngEd program, we can create the best community.

This initiative works on increasing and building upon the skills the community already has in a real world setting, and having a place to showcase those achievements and accomplishments (via the EngEd content program).

This Contribution Initiative is strictly restricted to the EngEd community.

EngEd Community Contribution Submission Process

  1. To submit an EngEd feature contribution for consideration, be sure to first check past feature suggestons to ensure relevance and prevent overlap. Hint: Use the this EngEd Content Suggestion form to propose article topic for approval and get feedback on topic ideas. View content form here
  2. When you're ready to submit a suggestion for review, submit your issue with details on what you would like to see added to the EngEd application/program.
  3. Suggestions will be reviewed by the Section team for relevance, and quality.
  4. Once suggested features have been incorporated into our backlog, the Section team will approve your issue and create a pull request to be worked on by the EngEd community.

Extra Information

Review process

Once you have opened a PR with your fully prepared article and accompanying images (according to the provided instructions), it enters a queue of articles to be reviewed by our technical review committee. Any required edits will be requested via comments within the PR in GitHub. Articles will either be approved (for publishing) or sent back with requested revisions.

Note: Articles requiring very few edits will be given priority in the review queue, and we reserve the right to refuse any articles that do not adhere to quality standards. PRs with no response from members (comments, edits) after a period of 10 days will be closed (but are able to be reopened if needed).

As a community, we are continually striving to add value to our content pool through trusted pieces of content that help enrich the larger engineering community.

Updated to continue increasing that level of quality and value for the community - we’d like to notify everyone of an update in the payout structure. 3/3/21

Updates to review processes:

We are introducing an improved topic suggestion form that will gather more developed details of your content idea. Acceptance of article ideas will consider originality, expected value for readers, overlap with existing content, and quality of the topic outline provided.

Articles are expected to be clearly understood, well-written, pre-checked for English grammatical issues, and technically accurate (with code tested).

We request articles to be cross-checked for readability.

All submitted articles should be BOLD & CLEAR, free of any lengthy, complex sentences, and/or common errors.

(We may waive for 1st-time contributors - to help them get familiar with the process, style, and quality we expect.)

All other formats payout will be as follows:

  • Articles with (little to no extra revisions needed) payout will be $100.00 USD ($150.00 USD for tutorials)
  • Articles with (2+) and up rounds of revisions we will consider closing the PR

What counts as a round of revision?

  • Any extra (major) steps that take a reviewer away from the actual revision process (revising, editing, and proofreading) and causes a shift towards content creation.
  • Any (major) incorrect code snippets (all code should be tested - contributors should take advantage of free tools such as repl.it).
  • Instances when the content is too difficult to understand.
  • PRs that may lack sufficient unique* value - (any and all comments made by reviewers to draw out more value from the article are great and encouraged but should be limited)

*by unique we mean content that can NOT simply be found by looking up the official documentation.

Note: We will start by calling a “round of revision” - any major back-and-forth between reviewer and contributor.

We will highlight articles that are of good consistent quality - to have as examples of the overall quality and style we are looking for.

Use your EngEd community as a resource - get to know each other and ask for a revision from a fellow contributor before submitting a final draft.

Below you will find MORE examples to reference and help guide you write fantastic content!

Please do not hesitate to reach out at any time - we’re always happy to help.


Example Format Structure

Content can include:

  • How-to guides
  • Tutorials
  • Software reviews
  • New technology introductions/overviews

Suggested topic areas (but certainly not limited to):

  • Network Engineering
  • DNS Routing
  • BGP
  • Caching
  • Web Application Firewall
  • Servers
  • Reverse Proxy Technology
  • Kubernetes
  • Docker
  • Cloud Native Technologies

How-To (use) Guides:

What is the Scope and Purpose of the Guide

Introduce the audience to the software or tech you are writing about and explain what is its purpose, and be sure to highlight any of its main benefits and features.

Introduce the purpose of your How-To Guide, what functionalities of the proposed software will you be covering? Assume the reader is smart but has no prior exposure to any common terminology or prerequisites about the topic. (cite other EngEd articles or sources if applicable)

How-To Guides Overview

Provide a brief description of the overall processes of the software, and how the user may need to work with the system. When needed, reference related processes and corresponding sources

  • Give Step-by-Step Instructions for using the software or system
  • Instructions
  • Conventions
  • Errors, Malfunctions, and Emergencies
  • Quick-Reference tips
  • Screenshots

(You may choose to include a process flow diagram to accompany the text. Consider including images and/or diagrams throughout your guide to introduce the audience to new workflows)

Tutorials Format:

To ensure the audience is getting the best experience - make sure you research other tutorials on the subject - this will help make you write a more complete and unique tutorial with a higher chance of being found and helping someone out. This also helps to narrow your focus as you research and begin to write. A bit of history about the technology being referenced or talked about might be helpful for the beginner audience.

Before starting make sure you pinpoint the problem your article is going to solve for the audience. If you are writing a tutorial, it is because you have noticed a pain point you’d like to address. When framing your tutorial it would help to identify your audience - who is this tutorial going to be written for - and who will be reading it. Tell the audience what a successful task looks like - and guide them through the process. Make the tutorial as user-friendly as possible - by including screenshots, tips, code examples, anything you think would benefit the audience as they try to replicate the tutorial. Don’t forget to get the audience involved by asking for feedback - or leave a call to action - for the reader to try out the skill they just learned about.

  • Make examples concrete
  • Audience should learn by doing
  • Clear understanding of how to start
  • Should require minimum explanation
  • Immediate sense of accomplishment

For some more information on how to write software documentation watch this video.

Tutorial Format Example

  • Title
  • Introduction
  • Goals (Optional)
  • Prerequisites
  • Step 1 — What to do first
  • Step 2 — What to do next
  • Step n — What to do last
  • Conclusion

Software Reviews:

Detailed Code Review Checklist

  • Be Fair: When comparing software(s) - be sure to include both the advantages and disadvantages of the software being compared or reviewed
  • Share why you believe this review to be helpful - describe your experience with the software (including extensive screenshots when applicable) - what problem did the software solve for you?
  • Test, Learn, & Test again: - Take your time researching new interesting topics you choose to explore & ensure any included code blocks have been thoroughly tested - exactly as stated in the review - to help cut down revision time.
  • Share any tips, techniques, and tricks you’ve discovered along the way, what helped you improve your coding experience - do not shy away from including details that may help the audience along the way.
  • Coding best practices & Proper code formatting: While writing your software review, check the code formatting to help improve readability and ensure that there are no barriers for the audience to get started:
  • Non Technical requirements: (Readability is very important) Get a feel of a story reading while reading through the software review.

New Tech Introductions Reviews:

  • What new and exciting technology are you going to research and write about?
  • Why are you introducing the EngEd community to this new technology - what is exciting about it?
  • Who will be the most exciting about this new tech - who is the ideal audience in your mind that would benefit from the review?
  • Layout any needed background information on the new tech being introduced.
  • Include any needed background on the situation, industry, or in the literature to best explain the new technology.

New Tech Introductions Review Format Example:

  • BRIEF SUMMARY- Your tech introduction should be a self-contained topic and must be an accurate interpretation of what is presented.
  • INTRODUCTION of the NEW TECHNOLOGY – a short introduction/description of the technology that is being reviewed. The introduction should contain all needed technical detail for the audience to replicate themselves and it should give the reader a clear understanding of how the technology works.
  • POSSIBLE APPLICATIONS of the new tech – explain how you have used this technology or how this technology may be used in the future.
  • PROS & CONS– outline the advantages and disadvantages of this new technology from your own experience/point of view and support it using relevant examples and sources.
  • CONCLUSION - include any next or final steps summarizing the technology introduction - that serves as a good launchpad for the audience.

Other subject matter samples:


Example Article Submission

title: A Brief History of Container Technology

description: A brief history of container technology and how it has fundamentally altered the development of software today.

The Beginning

Container technology is a method of packaging an application so it can be run with isolated dependencies, and they have fundamentally altered the development of software today due to their compartmentalization of a computer system. Yet, where did this technology come from, and what is the history of container tech?

Container technology was born in 1979 with Unix version 7 and the chroot system. The chroot system isolates a process by restricting an application’s access to a specific directory, where this directory comprised of a root and child directories. This system was the first glimpse of an isolated process, and it was soon adopted and added into BSD OS in 1982; however, container technology would unfortunately not progress over the next two decades and remain dormant.

The Adolescent Years

Container technology finally picked up steam in the 2000s with the introduction of Free BSD Jails. “Jails” are partitions of a computer, where there could be multiple jails/partitions on the same system. This jail system was further refined in 2001 with Linux VServer with the partitioning of resources, which was later linked to the linux kernel with OpenVZ in 2005, and jails were combined with boundary separation to create in Solaris Containers in 2004. After jails, container tech further progressed with the introduction of control groups in 2006.

Control Groups or cgroups were implemented for accounting and isolating the usage of resources like the CPU and memory. They were soon used and built upon in LXC (linuX Containers) in 2008, and this was the most complete and stable version of container technology at the time, as it worked on the Linux kernel without any patches. Due to LXC’s reliability and stability, many other technologies built on LXC, the first of which to be Warden in 2011 and more importantly Docker in 2013.

The Golden Age

Even though container technology had remarkable improvements from 2000-2011, the introduction of Docker changed everything and single-handedly led to a Renaissance in container technology. Docker built its foundation on two systems, LXC and libcontainers. Libcontainers came from LMCTFY, which was an open source container stack where applications created and managed their own subcontainers. In addition to building on previous software, Docker had an easy to use GUI and was capable of having multiple applications with different OS requirements run on a single OS. Due to these phenomenal qualities, Docker blew up, leading to 100 million downloads within a year, and after Docker’s success, another technology, rkt (pronounced Rocket), tried to fix some of Docker’s problems by incorporating more rigorous security and production requirements.

The impact and popularity of both these technologies grew as they both interacted with Cloud Native Computing Foundation, a global hub of developers, foundations, and vendors. This spurred community involvement and collaboration, which continued to grow after Microsoft allowed Linux containers (which included rkt and Docker) to be natively run on Windows computers in 2016. Previously, containers were mostly linux based technology, but this decision lead to Microsoft becoming a major influence in container technology, seen by both Process and Hyper-V containers on Windows computers.

Container technology’s momentum continued in 2017 through the introduction of the Kubernetes, which was a highly effective container orchestration technology. After Kubernetes’ inclusion into cloud providers like CNCF and its support from Docker, it became the industry standard, and the combination of Kubernetes and other container tools, such as Flannel, lead to further improvements in container technology. In 2019 one still sees the Golden age of container technology, and it continues to reach the masses through Containerd, Containership, and many other pro-container figures and websites, leading to continual popularity and progression in the container technology industry.