search

100Automations / Website

We’re supporting tools and micro services to help simplify open source development for the wider Civic Tech community. We welcome ideas and projects in all stages - connect with us and let’s build 100 automations.
https://100automations.org/
GNU General Public License v3.0
13 stars 14 forks source link

A proposal for streamlining the process of adding a new guide page OR project page/card. #189

Open akibrhast opened 3 years ago

akibrhast commented 3 years ago

Dependency

While the below proposal is going to be discussed in terms of the particularity of the guide pages. It can also be applied easily to new project cards that needs creation.

Tentative Steps

  1. Create an endpoint with a form, and https://quilljs.com/
  2. In the form make these fields required. [title,description,status,display] and also ask for their github username
  3. Let them write out their article/guide page in the quiljs section.(we could also do a template renderer here)
  4. On submit ensure that the github username supplied in the form exists in the github username section of the onboarding spread sheet.
  5. If it exists create a new issue on GitHub using the data from the form with label 'newguidepage' . For example.
    Example New Issue That will be created
---
title: Writing an Article for Your Automation
description: If you want to write an article about your automation, consider these tips.
status: in progress
display: true
---
CONTENT GOES HERE THAT WAS WRITTEN IN QUILLJS THIS SHOULD ALREADY BE IN HTML FORMAT (WHICH THE GITHUB ISSUE RENDERS PERFECTLY)

  1. Discussion/Edits between folks on the content of the article. No styling discussions needed cause that has been standardized.
  2. Discussion Ends and Finalized. a 'finalized' label is added to the issue
  3. A github action checks for issues labeled 'newguidepage' + 'finalized' that has been labeled finalized for over an hour+ , extracts the markdown from the issue. And creates a new pull request by creating a markdown file with the name specified in the title in the respected folder. The pull request should of course link to the issue.
  4. Another github action get notified of this pull request and runs an action that merges the new guide pages into master from within the context of the action. Takes screen shots of what the new guide page woud look like on the live site in chrome, edge, firefox, mobile, desktop, tablet. and adds the images as a comment to the pull request.
  5. A developer riding the subway looks at the pull request from his cell while enjoying a delicious cup of coffee in the cold winter morning and.
  6. MERGE.

What that boils down to.

  1. Someone writes and article
  2. It goes through revision
  3. Its merged

Anyone can get started on writing an article without worrying about understand or needing to learn markdown and formatting and this and that(and by anyone I mean anyone in the team -- pms,ux,ui,content,dev,research,etc....)

p.s. I already have a script that does yaml validation, we can use on either project cards or guide page front matter

NivenPrasad commented 3 years ago

@akibrhast - this looks awesome. Maybe we can test it with a guide that we're currently writing?

For use with automation cards, perhaps we can test with the automation that Darren is about to complete soon.

On the Guides vs Article clarification - here is a list of guides that we currently have. You'll see that the topics covered in Guides are How To's on a number of topics around automation vs more than just how to document in a readme.

Contrast this with some of the example articles in the Writing Articles Guide. You'll see they're more long form with elements of storytelling.

Hope that helps but happy for discussion at next meeting to clarify further.

henlatourrette commented 3 years ago

Product will have a discussion about this issue before we could move forward with next steps.

henlatourrette commented 3 years ago

@akibrhast is researching and will update us on the issue again.

akibrhast commented 3 years ago

We don't have MVP yet. This proposal is definitely not MVP.