WTD Portland 2021 Writing Day: crowd source style guides to include on the Write the Docs style guide page

writethedocs / www

The main website for Write the Docs.

http://www.writethedocs.org

Other

1.32k stars 510 forks source link

WTD Portland 2021 Writing Day: crowd source style guides to include on the Write the Docs style guide page #1499

Closed barriebyron closed 3 years ago

barriebyron commented 3 years ago

This issue is a collection of improvements we want to make for the Write the Docs Style Guide page.

@Bradamant3 is our chief WTD style guides doc PR wrangler.

if you submit PRs to this page, please tag Jennifer @Bradamant3 so she can help us resolve our expected merge conflicts. Our work might be ongoing.

Goals:

Remove duplicates
Move bias to new page/section @Bradamant3
Move accessibility to new page/section @Bradamant3

Add trusted resources in logical groupings and improve navigation

Looking for champions/wranglers for:

release notes Elaine
command line interface docs @barriebyron
error messages thank you Catherine Heath

If folks have examples of style guides or good how-to articles in their bookmarks etc that aren't on the page, please add them to this issue

barriebyron commented 3 years ago

Theo likes command lines https://github.com/theomelo @theomelo

barriebyron commented 3 years ago

Release notes style guides/resources Anne Kohler Jessica Nealon

Elaine https://github.com/epersonae is our volunteer wrangler for organizing and navigation @epersonae

resources that Barrie has bookmarked

barriebyron commented 3 years ago

consider adding a README style guide section https://www.writethedocs.org/videos/eu/2017/hi-my-name-is-readme-raphael-pierzina/

barriebyron commented 3 years ago

Theo and Barrie error message guides crowd source here resources

AnneKohler commented 3 years ago

For Release Notes: I've filed 2 issues (1503 and 1505) for a broken link and a format suggestion.

epersonae commented 3 years ago

I submitted a pull request for some reorganization, fix a broken link (not sure if same as @AnneKohler), and add a note about overarching structure of the page. https://github.com/writethedocs/www/pull/1504

Jessicancomm commented 3 years ago

Release Notes Examples: https://slack.com/release-notes/mac https://confluence.atlassian.com/jirasoftware/jira-software-release-notes-776821069.html https://kb.madcapsoftware.com/Content/Flare/General/GEN1066F_-_Flare_2021_Release_Notes.htm https://www.teamwork.com/roadmap

AnneKohler commented 3 years ago

Release Notes Resources: https://opensource.com/article/17/3/how-to-improve-release-notes https://announcekit.app/blog/the-best-and-the-worst-app-release-notes-that-will-inspire-you/ https://www.appcues.com/blog/release-notes-examples https://blog.testlodge.com/importance-of-writing-release-notes/ https://uxdesign.cc/the-art-of-writing-great-release-notes-6607e22efae1 https://ffeathers.wordpress.com/2017/08/19/how-to-write-release-notes/ https://www.parlor.io/blog/transforming-your-release-notes-into-product-announcements/ https://slite.com/learn/release-notes

Jessicancomm commented 3 years ago

It would also be good to have a What to Avoid section: What to Avoid: https://techcrunch.com/2015/09/04/app-release-notes-are-getting-stupid/ https://mjtsai.com/blog/2019/03/12/bad-release-notes/ https://www.klariti.com/technical-writing/2015/05/08/release-notes-mistakes-to-avoid/

Jessicancomm commented 3 years ago

To add to the Resources section: https://slite.com/learn/release-notes

barriebyron commented 3 years ago

thanks @Jessicancomm I added this morning!

plaindocs commented 3 years ago

Thanks for all of your contributions folks! :-) :-)