Frictionless Documentation

--- title: 'Frictionless Documentation' disqus: f10s --- <center align=center> # <img alt="Accessibility" src="https://raw.githubusercontent.com/SMotaal/f10s/master/assets/Frictionless.svg?sanitize=true" height=72 /> Frictionless Documentation [`f10s/docs`](https://github.com/SMotaal/f10s/blob/master/DOCS.md) Collective rethinking of documents that drive our collective efforts.  </center> ## Overview The idea is to start an effort for various 101 docs and create variations that are suited to different reading styles and preferences, not unlike i18n, but which are frictionless and/or accessible! <center align=center> *"baby steps though… nothing big!"* </center> For starters, folks could write the missing README files for how to use GitHub… etc, then move on to other documents in our shared knowledge base, for the open source collective. <center align=center> *"it's like collective i18n effort… to some extent!"* </center> Doing that will likely be the missing agent that will finally help close the gaps between the various frames of reference, and that will make it possible to reason about the unknown expanse that leaves all of us unsure where to begin. --- ### Motivating Examples - You can look at those two great examples by the [Autistic Self Advocacy Network](https://autisticadvocacy.org): 1. [Inclusive Meetings - Plain Language](https://autisticadvocacy.org/wp-content/uploads/2019/06/PL-Inclusive-Meetings.pdf) 2. [Inclusive Meetings - Easy Read](https://autisticadvocacy.org/wp-content/uploads/2019/06/er-inclusive-meetings.pdf) The point though, those are merely two of any number of interpolations that will suite readers of some shared difference(s). - > Please feel free to add your own motivating examples --- Opting for a more frictionless style of communication does not mean we need to stop using bad tools and start using good ones, only to adopt that mindset when we use tools, and then we can decide if we need more adaptable ones. Here are examples of things some of us did with the usual tools that were meant to make them more frictionless: - https://github.com/nodejs/nodejs.dev/pull/410#discussion_r382932068 - > Please feel free to add your own! --- ## References ### Threads - [**`Feb25`** @SMotaal/f10s](https://github.com/SMotaal/f10s/blob/master/DOCS.md) - [**`Feb25`** @frictionlessly](https://github.com/frictionlessly) ### Venues - [**`Feb25`** CHAOSS Community Meeting](https://docs.google.com/document/d/1PMDWc6xMe0fNE7shxTK5_HE_ykRBG5w55_Zx5hvzsEY/edit?pli=1#heading=h.4o1aukwz7b7v) - [**`Feb25`** OpenJS Foundation slack](https://openjs-foundation.slack.com/archives/C0K2NFFV1/p1582654735005400?thread_ts=1582590438.001200&cid=C0K2NFFV1) <!-- ## Table of Contents [TOC] ## Beginners Guide If you are a total beginner to this, start here! 1. Visit hackmd.io 2. Click "Sign in" 3. Choose a way to sign in 4. Start writing note! User story --- ```gherkin= Feature: Guess the word # The first example has two steps Scenario: Maker starts a game When the Maker starts a game Then the Maker waits for a Breaker to join # The second example has three steps Scenario: Breaker joins a game Given the Maker has started a game with the word "silky" When the Breaker joins the Maker's game Then the Breaker must guess a word with 5 characters ``` > I choose a lazy person to do a hard job. Because a lazy person will find an easy way to do it. [name=Bill Gates] ```gherkin= Feature: Shopping Cart As a Shopper I want to put items in my shopping cart Because I want to manage items before I check out Scenario: User adds item to cart Given I'm a logged-in User When I go to the Item page And I click "Add item to cart" Then the quantity of items in my cart should go up And my subtotal should increment And the warehouse inventory should decrement ``` > Read more about Gherkin here: https://docs.cucumber.io/gherkin/reference/ User flows --- ```sequence Alice->Bob: Hello Bob, how are you? Note right of Bob: Bob thinks Bob->Alice: I am good thanks! Note left of Alice: Alice responds Alice->Bob: Where have you been? ``` > Read more about sequence-diagrams here: http://bramp.github.io/js-sequence-diagrams/ Project Timeline --- ```mermaid gantt title A Gantt Diagram section Section A task :a1, 2014-01-01, 30d Another task :after a1 , 20d section Another Task in sec :2014-01-12 , 12d anther task : 24d ``` > Read more about mermaid here: http://mermaid-js.github.io/mermaid/ ## Appendix and FAQ :::info **Find this document incomplete?** Leave a comment! ::: ###### tags: `Templates` `Documentation`