Create a Guide: Writing Short Descriptions for Your Automation

[NivenPrasad]

Overview

We need to create website content with a mark-down approach so that development can be easily updated. This is the issue to create a mark-down file for the "Writing About Your Automation" guide.

Action Items

• Write mark-down for the guide instructions in a comment on this issue.
• Create a mark-down file for this guide and add it to a folder called _guides
  • Call the file a name with dashes that is as short as possible
    • name: writing-short-descriptions-for-automations.md
  • Add the following header to the file:

---
title: Write a Short Narrative Description about Your Automation
description:  A good narrative description will increase targeted traffic to your repository.  This guide helps you create one.
status: active
display: true
---

Resources/Instructions

Figma Board for 100 Automations Website Design

[NivenPrasad]

---

title: Write a Short Narrative Description about Your Automation
description: A good narrative description will increase targeted traffic to your repository. This guide helps you create one.
status: active
display: true

Write a Short Narrative Description about Your Automation

You will need to write a short description about your automation so that people will understand what it is about and why it's valuable.

Uses:

• project card on 100Automations.org website
• read.me on your repository
• announcements (linkedIn, etc.)

Elements:

The description should have the following elements:

• A Problem Statement
• Description of Solution
• A practical example where you can see this (recommended)
• Future development (optional)

Examples:

Here are two examples:

Example 1:

GitHub’s Contributor’s endpoint only shows the people who put in pull requests. On cross functional teams that use GitHub to manage projects, contributions from non code contributors (Designers, Product/Project Managers, Business Analysts, Q/A testers, etc.) are represented by comments on issues.

True GithHub Contributors delivers a consolidated list of who contributed and how many times. This code can be seen on Hack for LA’s project pages, where the contributors are represented by their GitHub Avatar in the Contributors section.

Includes:

• A Problem Statement
• Description of Solution
• A practical example where you can see this (recommended)

Does not include:

• Future development (optional)

Example 2:

When using Github and Jekyll it is easy to end up with files that are missing data types, with no built in way to enforce uniformity.

The Jekyll-Gather-Data-Types automation creates reports that identify what data types are being used across all files in a collection and what might be missing from individual files in order to target code for remediation.

Future functionality could include providing the option of using GitHub actions to prevent incomplete files from being committed (PRs).

Includes:

• A Problem Statement
• Description of Solution
• Future development (optional)

Does not include:

• A practical example where you can see this (recommended)
  Reason: because the use of the automation does not produce artifacts that can been seen through a browser.