jamesmrollins commented 3 years ago

Please Reference Lucid Chart Link Below

Lucid Chart - Story 10

Reference

Actions · department-of-veterans-affairs/vets-website (github.com)

Story 10 - Markdown and Bookdown actions streamline and ensure quality user-edits of on-line publications.   

Pain points

Users must have detailed knowledge of markdown file locations to update a given topic within the same repository. 
Users must have advanced working knowledge of markdown language to avoid common md format, spelling, 508 violations and image and video linking errors.

Affected users

Facilitators, HQ, Quant, Sim UI  

Recommended Alternative

[ ]  Describe a procedure using commonly available website search tools to find instances of a word, topic or sentence. 
[ ] Develop, test and deploy an action that allows single-point editing of markdown files and automatically updates them in their various inter-repository and intra-repository locations. 
[ ] Create markdown procedures in Team PSD Manual. Leverage commonly available training and information available on websites such as markdownguide.org and bookdown.org.
[ ] Include a list of common mistakes and format assertions we use when making markdown files.
[ ] Write procedure for properly linking video and image files ( including 508 metadata). Explain how to use existing spell checker, link checker, md linter and find-n-replace actions using GitHub branches.
[ ] Need to create a master md stylistic rules (see discussion below).

lijenn commented 2 years ago

For markdown files linter rules/wishlists on the lzim/mtl repo, discussed HQ WG 2/17: (@lijenn will fix copy/paste formatting of the chat)

[2/17 3:49 PM] Zimmerman, Lindsey E. Use Sentence case consistently with instructions.

[2/17 3:55 PM] Zimmerman, Lindsey E. for numeric steps

[2/17 3:56 PM] Nallajerla, Meghana R. Documentation Review:

Be consistent throughout (ie, sentence case throughout, & or 'and') Use "and" instead of "&" Refer to Style Guide for guidance Stick to sentence case with instructions to an implied user (ie, "Select this,")

[2/17 4:04 PM] Zimmerman, Lindsey E. Look for whenever there is a mix for important clinical/operations considerations in the same list as technical tips/tricks. Keep separate with standard formatting rules.

[2/17 4:06 PM] Zimmerman, Lindsey E. Are there grammar linters or GitHub Actions? "data" tabs, which show or Data tab, which shows

[2/17 4:10 PM] Zimmerman, Lindsey E. Look for any inconsistently applied things like note for #4 and "Tips & Tricks" for #3. "Note:" (keep consistent) "Tips & Tricks" (down below)

DECISION: We will use & (ampersand) for "Tips & Tricks" (because it's not a complete sentence) we will use "Tips & Tricks" in a standard way for tech tips!

[2/17 4:12 PM] Zimmerman, Lindsey E. QA process: Make sure the bullets are in order of what you actually need to do. e.g., if you need the filter panel to use the data tabs, then how to use the filter panel needs to be at the top of the list of questions that use filtering in data tabs.

[2/17 4:14 PM] Zimmerman, Lindsey E. Follow the language that Lindsey repeatedly uses closely (when applicable), as this is likely the most vetted explanations she's learned over the last 7+ years of MTL development with partners.

[2/17 4:16 PM] Zimmerman, Lindsey E. Somehow the prompts for the viz tabs got placed down with the data tabs. See screenshot below:

[2/17 4:18 PM] Zimmerman, Lindsey E. WATCH OUT FOR THIS INCONSISTENCY: Two questions on one bullet. Above we have one question one bullet. DECISION: For TOC consistent prompts, one question per bullet.

matthewtomo commented 3 weeks ago

adjudicate_memo

@jamesmrollins @matthewtomo @ljmoody

Marking as closed since we are no longer pursuing this for now

lzim / teampsd

ICEBOX story_ g: User needs markdown and bookdown actions to streamline devops and ensure quality of user edits of on-line pubs #2125