Skip to content

Latest commit

 

History

History
85 lines (54 loc) · 5.19 KB

GDocNotes.md

File metadata and controls

85 lines (54 loc) · 5.19 KB
Raw

Write The Docs Portland 2019 Materials from Slack chat

  1. All videos: https://www.youtube.com/watch?v=RIiIOFBS5DM&list=PLZAeFn6dfHpmuHCu5qsIkmp9H5jFD-xq-

  2. Preparing for Write the Docs PDX 2019 https://aaronthayer.net/blog/preparing-for-WTD-2019/

  3. WTD PDX 2019 - Day 1 Recap https://aaronthayer.net/blog/wtd-day-1-recap/

  4. WTD PDX 2019 - Day 2 Recap https://aaronthayer.net/blog/wtd-day-2-recap/

  5. TAGS 6.0 https://docs.google.com/spreadsheets/d/1hBqEmrGkW44z29lNCPIKLoz5kUZF64K202e7sXAWFY0/edit#gid=8743918

  6. COMICS IN DOCS https://tessneedham.blog/2019/05/20/comics-in-docs/

  7. Write the Docs 2019 Unconf, API Ref Docs https://docs.google.com/document/d/1WQxv-wEPDWTQQihnV4qLV5l_3MPGfEAv05Fiq73ALBc/edit

  8. Write the Docs photo gallery https://www.flickr.com/photos/writethedocs/sets/72157691507514803

  9. Google sheet of unconf schedule: https://tinyurl.com/wtd-portland-2019

  10. In one of the unconference sessions, I mentioned the concept of abstracted graphics, which I learned from this presentation https://www.dropbox.com/s/sc1lvbh30gzt7dr/Dollars%20&%20Sense%20of%20Visuals%20in%20Content%20-%20STC%20Summit%202019.pptx?dl=0#

  11. Kate's amazing photos can be seen on Write the Docs Flickr page: https://www.flickr.com/photos/writethedocs/sets/72157691507514803/with/47831491072/

  12. official mermaid app: https://mermaidjs.github.io/mermaid-live-editor/

  13. whimsy drawings (the main change is CSS): https://alicja.dev/mermaid-live-editor/

  14. AWS example (pretty loooong link): https://alicja.dev/mermaid-live-editor/#/edit/eyJjb2RlIjoiZ3JhcGggTFJcbkNsaWVudCg8c3BhbiBjbGFzcz0naWNvbiBicm93c2VyJz48L3NwYW4-IENsaWVudCkgXG5DRig8c3BhbiBjbGFzcz0naWNvbiBjbG91ZGZyb250Jz48L3NwYW4-IENsb3VkRnJvbnQgRWRnZSBsb2NhdGlvbilcbkFHKDxzcGFuIGNsYXNzPSdpY29uIGFwaWdhdGV3YXknPjwvc3Bhbj4gQVBJIEdhdGV3YXkpXG5MYW1iZGEoPHNwYW4gY2xhc3M9J2ljb24gbGFtYmRhJz48L3NwYW4-IEFXUyBMYW1iZGEpXG5cbkNsaWVudCAtLT4gQ0ZcbkNGIC0tPiBBR1xuQUcgLS0-IExhbWJkYSAiLCJtZXJtYWlkIjp7InRoZW1lIjoiaWNvbnMifX0

  15. DRAW THE DOCS https://drive.google.com/file/d/1vt--7aacuoZjP2BMghT6lMxVPlsKGfos/view?usp=sharing

  16. GITDRAWING https://xkcd.com/1597/

  17. Storytelling with Git https://speakerdeck.com/aviflax/storytelling-with-git

NOTES

  1. dam Altman [May 21st at 3:39 AM] Notes from the API Docs unconference (table 1) with @mikejang:

  2. A couple people use postman pro and like it. They thought it was easy to use, setup docs within the postman and publish to git. One person had a problem that it publishes to git as a single line of JSON. One person was able to establish a relationship with the CEO, and found them responsive to feature requests.

  3. One person uses widdershins / slate to publish the docs. It was a bit of work to setup but works smoothly now.

  4. One uses Doxygen (and has a SOAP API). Doxygen has a long conf file, but this person was able to self-learn it and could make changes and was able to style the output (and use something called comments).

  5. People noted a struggle of when you have to support both SOAP and REST API docs.

  6. Tutorials: people are mainly using separate docs for that. (I mentioned we have a product we're going to release that allows you to "reference" your API specs from contextual docs... perhaps will have an unconference to preview that labeled Redocly Portal).

  7. ADE (an acronym we all should learn: API Development Environment.) Everyone had used Postman, also check out insomnia.

  8. One person used Stoplight and thought it was easy to paste yaml in, edit, and save (export). They have some other workflow that required some engineering to do something with s3.

  9. One person uses and does not recommend Modx. The build pipeline sounds complex, using artifactory, and layering on some customer license/authentication part.

  10. Notes from Inclusivity unconference (facilitated by @ilona ): Inclusivity for accessibility (There are more questions than answers in these notes, and sometimes you have to start with questions to find a way to some answers.) Having people from different backgrounds on your team who feel comfortable being themselves bring a unique perspective to your docs. How do you help people feel comfortable being themselves? How accessible can your docs be, if the product you are documenting is not? UX and design often have standards for accessibility. How can we leverage those standards for docs? See a step in the right direction below. A question I had but didn't voice during the unconference: How do you get time built in to make sure your docs are accessible (on a team where you struggle to get time built in for docs at all)? Guidelines and resources that help writers write inclusively the first time really help. A not-even-close-to-complete list of some things to consider for accessibility: reading level, left-to-right vs. right-to-left reading, idioms/sayings. Resources for accessibility: @Nicola from Google is working on UX/design accessibility standards for docs and hopes to work with another co-worker (is that you? we met, but I don't remember your last name. please at-mention yourself.) on making them external. Check out 18F Content guide (thank you to the person who recommended this! can you at-mention yourself). Check out BBC content guide (same as before).

  11. Some topics of the unconference talks