classic5594
commented
4 years ago Looking over 1st draft of article
Open classic5594 opened 4 years ago
classic5594
commented
4 years ago Looking over 1st draft of article
Contribution Guidelines
Welcome to Section’s Engineering Education program. This program is dedicated to providing a community-generated pool of educational content that is useful for engineers of every level. To begin, we’d recommend reviewing our most recently published content at section.io/engineering-education/ to get a sense of:
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.
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.
Requirements for New Contributors
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.
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
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).
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.
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.
Review and approval processes
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.
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:
Suggested topic areas (but certainly not limited to):
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
(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.
Tutorial Format Example
Software Reviews:
Detailed Code Review Checklist
New Tech Introductions Reviews:
New Tech Introductions Review Format Example:
Other subject matter samples:
Testing to Submit test2