Establish standardized guide formatting

[NivenPrasad]

Overview

We need to establish consistent formatting across the guides.

Action Items

• Audit and fix current guides for consistency
• Decide on heading hierarchy
• Audit all guides to get current status (see below)
• add categories to metadata - Add Categories as Metadata for the Guide  #375
  • check/confirm all guide categories - Establish Guide categories  #397
• confirm builder/contributor usage - Swap the usage of "Build" and "Contribute" #395
• finalize CSS - Update the CSS for the guides #334 - this is down to minor bugs and formatting subtleties
• Deal with title wrap (vertical center? character limit?) - small enough issue, we can set aside and prioritize later
• Fix obvious content/markup bugs (see below)
• Address assorted quirkiness (see below)

Resources/Instructions

• Create a Guide: Supporting Your Automation with Community  #43
• Create a Guide: Writing Short Descriptions for Your Automation #42
• Directory for all guides
• Revise Guides wireframe design #174

---

Guide Review

Proposed changes to all guides:

• take out the H1 title from the content - it repeats the H1 title in the header - remove second H1 title from all guides #386

Not Written

Start Contributing

• UNWRITTEN - it's a stub, no info about adding an existing code package finish the Start Contributing guide #355

Using An Automation

• UNWRITTEN - blank. Propose we delete this guide for now and backlog an issue to create a guide. Proposal: remove "Using An Automation" till post-MVP #388

Start Building

• broken link : Guide on Creating an Automation Repo : page does not exist content replaced
• broken link : automation workflow overview : links to create a blank wiki page Create automation workflow overview  #354 content replaced

Bugs / Broken

Preparing Your Automation for Publication

narrow. Longer headings are odd in the sidebar

• _formatting: broken headings, goofy sidebar, hr misinterpreted by jekel _ - fix guide: Preparing Your Automation for Publication #385
• broken links: Writing About Your Automation, Supporting Your Automation with Community - fix guide: Preparing Automation - broken links #389

Creating a Good Read.me for Your Automation

pushed wide by fixed width code

• clarify code text with additional styling (quote/indent?) - fix guide: Good Readme - clarify code formatting  #387 - post-MVP

Writing an Article for Your Automation

narrow

• has extra hand-made ToC links in the content

Quirky

Project Card Anatomy

pushed wide by image

Self-Evaluating a New Automation Idea

longer headings odd in the sidebar

Workflow Guide For Builders

pushed wide by image. text in image accessibility

Workflow Guide For Ideators

pushed wide by image. text in image accessibility

As Expected, More or Less

Supporting Your Automation with Community

narrow

Submit Idea

narrow

Write a Short Narrative Description about Your Automation

narrow

Creating a Good Project Image

narrow

• has edit footer - pr removed old "edit" footer #377

Creator Overview

• empty ToC - added headings #378

How to suggest a guide for 100 Automations

• broken markup for link fixed link #379

Write your Open Source Automation Creator Bio

narrow

• messed up ToC due to misused headings - redo headings to work with auto ToC #380

[nahyungkim1220]

This is a mock-up that shows the 2 main styles of guides.
Bullet point guides: Supporting Your Automation with Community, Preparing Your Automation for Publication
Narrative guides: Self-Evaluating an Automation Idea, How to suggest a guide for 100 Automations

Title

Instructions

A brief description of what we need from the user.

• Bullet-pointed guides
• Narrative guides
• Subheading

---

Bullet-pointed guides

Bullet-pointed guides tend to take up more vertical space, so they need a navigation section like the one above. Subheadings are organized by topics.

Example 1:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus vitae diam sed ex feugiat auctor et a nisl. Maecenas semper maximus lectus at molestie. Donec convallis feugiat neque ac faucibus. Nunc ornare malesuada elementum. Morbi vulputate erat vitae mollis pellentesque. Nunc volutpat mauris a velit gravida venenatis. Duis condimentum egestas viverra.

Integer ligula sem, cursus dignissim dolor nec, mattis commodo felis. Curabitur vel tortor non enim ullamcorper pellentesque nec sit amet elit.

Includes:

• Lorem ipsum
• Lorem ipsum

Does not include:

• Lorem ipsum
• Lorem ipsum

---

Narrative guides

Narrative guides are divided into sections of short sentences. Subheadings are organized by instructions rather than topics.

Example: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus vitae diam sed ex feugiat auctor et a nisl. Maecenas semper maximus lectus at molestie. Donec convallis feugiat neque ac faucibus. Nunc ornare malesuada elementum. Morbi vulputate erat vitae mollis pellentesque.

Nunc volutpat mauris a velit gravida venenatis. Integer ligula sem, cursus dignissim dolor nec, mattis commodo felis. Curabitur vel tortor non enim ullamcorper pellentesque nec sit amet elit.

---

Subheading

.
.
.

END

---

To propose/submit changes to this guide please edit the markdown file for this guide

[superbunker]

Didn't get to wiki page yet -- should have that set up later today.
But a little concerned that this overall thing might be too wooly for MVP?

[superbunker]

Refocused on just auditing the markup and basic structure. There's not a ton of changes, so I'll just review them here.

Guides using "standard" markup:

• creating-good-readmes-for-automations.md
• prep-automation-for-publication.md
• self-evaluating-new-automation-idea.md
• writing-articles-for-automations.md

Three guides have some non-standard markup:

writing-short-descriptions-for-automations.md — doesn't use H2s
proposed changes: just bump the h3s & h4s up a level

suggest-guide-for-100Automations.md — all H3, some bold-as-heading
proposed changes: Could use a little editing to clarify the sections, then apply headings by level

community-support-for-automations.md — doesn't use H2s
proposed changes: bump H3s to H2s. Simplify structure so H3 isn't necessary by removing word "overview" and add descriptive term at beginning of three bullet items. For example:

File_Name.md

This file does very helpful things

• Template: file_link
• Example: file_link
• Resources: links

overall: "END" is an H4
make this an h2 or a non-heading tag?

[superbunker]

Process questions: would it be better to edit the guides in my fork of Website and PR that, or individually edit/PR each edited guide?

Also, what would be the best way to share the edited drafts? Paste content here?

[Olivia-Chiong]

Please create individual PRs for each and tag @Olivia-Chiong or @NivenPrasad for review.

[superbunker]

Made markup changes to writing-short-descriptions-for-automations. Mostly just changed headings to properly nest. PR #153

Made markup and some content structure changes to suggest-guide-for-100Automations PR #154

[superbunker]

revised community-support-for-automations.md
Some notable formatting changes, gentle content edits, and a proposed End of File denotation
PR #157

[NivenPrasad]

Nice work @superbunker. Now approved #153 and #154. Inclined to have @ExperimentsInHonesty or @Olivia-Chiong review #157 given extent of changes/HTML edits in there.

[superbunker]

Drafted a guide to guide formatting in the wiki:
https://github.com/100Automations/Website/wiki/Guide-Template

[Olivia-Chiong]

Refer to this markdown https://github.com/hackforla/website/wiki/Template-of-a-project.md-file

[superbunker]

created guide_template.md and cleaned up the Guide to the Guide Template

[henlatourrette]

Assign back to @superbunker when dependency met.

[superbunker]

Propose that we get rid of the footer in all the guides ("END" or "END OF FILE" and the invitation to edit)

[superbunker]

@superbunker will try to figure out what's going on these days

[superbunker]

i'm working on it, more or less

[superbunker]

Bonnie: "Some of the guides look different than other guide pages. That should not be possible if we are using collections properly. Please make an issue to review with a bug label to figure out why and fix."

[superbunker]

moved Guide Review to main issue for easier tracking

[superbunker]

Proposed change to all guides: take out the H1 title from the content, since it repeats the H1 title in the header

[superbunker]

Carlos gunna take a swing at the weird CSS, in particular the goofy right margin of the content and smooshing the sidebar off screen when theres fixed width content

[superbunker]

Carlos, still swingin'

[superbunker]

The weird with issue seems to have been dealt with, at least on desktop.

[superbunker]

Guide formatting finalized. Major bugs and quirks fixed.