<commit_before>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:fb="http://ogp.me/ns/fb#">
  <head>
    <meta charset="utf-8">
    <link rel="icon" href="../../../../img/favicon.png" type="image/x-icon">
    <meta property="og:image" content="img/veronica.jpg" />
    <title><NAME> | Everything is Awesome</title>
    <link rel="stylesheet" href="../../../../css/normalize.css">
    <link href='https://fonts.googleapis.com/css?family=Changa+One|Open+Sans:300,400,400italic,700,700italic,800' rel='stylesheet' type='text/css'>
    <link rel="stylesheet" href="../../../../css/main.css">
    <link rel="stylesheet" href="../../../../css/responsive.css">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
  </head>
  <body>
    <header>
      <a href="index.html" id="logo">
        <h1><NAME></h1>
        <h2>{ learning and writing }</h2>
      </a>
      <nav>
        <ul>
          <li><a href="../../../../index.html">Portfolio</a></li>
          <li><a href="../../../../blog.html" class="selected">Blog</a></li>
          <li><a href="../../../../about.html">About</a></li>
          <li><a href="../../../../contact.html">Contact</a></li>
        </ul>
      </nav>
    </header>
    <div id="wrapper">
      <section>
        <h3>Writing READMEs that will make future you happy</h3>
        <h5>March 6, 2017</h5>

        <br/>

        <p>
        Most of us have struggled to decide what to include when documenting our projects. Weither you are posting your first project to a repository and unsure of the level of detail to offer about what your program does or you are improving documentation of an existing project to encourage others to contribute, staring at an empty Readme file can make us feel like we don't know where to start. I've made a quick guide to help you get jump-started. 
        </p>

        <p>
        <h5>What makes a README?</h5>
        Let's not sweat the Markdown, the flashy demos and screenshots, or the badges just yet. Good READMEs are more about <a href="https://robots.thoughtbot.com/how-to-write-a-great-readme">clear writing</a> - clearly stating what problem your program solves, it's use, and (if you're looking for contributors) ways of getting folks familiar and able to jump on board - than they are about all the flashy "extras". Let's go back to our sixth-grader-starting-essay selves for a moment and make ourselves an outline.
        </p>
        <p>
        <h5>Core Components</h5>
        You should always include an <b>introduction</b> to the project (and the problem it solves), list any programs or modules your user will need to have as <b>requirements</b>, and <b>installation</b> instructions. Most READMEs include troubleshooting information and a call to action if the author is hoping for contributers. The most important thing to keep in mind is that you are providing information to help someone use or improve your code. What do they need?
        </p>

        <p>
        In the beginning, most projects have one contributor <a href="https://www.youtube.com/watch?v=TdrEmZ35fxc">('tis I)</a>, and I learned that the READMEs that other folks found the most helpful were the ones that I had written not for an imagined future user, but for my future self. If I were to rediscover this project three years from now, what would help me start using it again? What would help me make my first commit after being away from the code (and the problem it solves) for so long? These questions guide the first draft of every README I write.
        </p>

        <p>
        <h5>Putting your best foot forward</h5>
        Even if you can hum along with every line of the Lancealot's self-absorbed opening song in Camelot, you reconize that writing code is more exciting when it's used and appreciated by others. It's now time to step outside your own head, put your user hat on, and think about why someone might want to use your project and what they will be wondering when they stumble on your README. I usually have a friend read my first draft over and ask them what they learned about my project and I adjust from there. 
        </p>
        <p>
        You can take the "have a friend read it" approach one step further by attending spirits or "docathons" that support other open source projects. I've found that reviewing the documentation of other projects by following the steps provided to prepare your first contribution will teach you a lot about what your own first-time contributors will benefit from! I consider "taking a walk in your contributors shoes" an important step toward becoming a compassionate documentation writer.
        <!-- Where can I suggest people go to hear about docathons? First thing that comes to mind is the write the docs twitter (or their local chapter's twitter) but what else? -->
        </p>
        <p>
        If you can throw in a little humor, that is sure to be appreciated as long as all the important elements are included and easy to find. This <a href="https://github.com/jrbl/kegs">version of the game "bottles and kegs"</a> was a project I stumbled upon months ago and it still gives me the chuckles.
        </p>

        <p>
        As you become more comfortable with your writing, you can take some time to discover the visual ways to provide your reader with infomation about your project.<br/> 
        There are many options:
        <ul>
          <li><a href="https://github.com/vzhz/friendly_terminal">Screenshots</a> allow potential users to preview the results of your program and inspire confidence. They are added to your document as you would an image, with <code>![text to show on rollover](https://github.com/your-name/your-repo/your-image)</code>.</li>
          <li><a href="https://guides.github.com/features/mastering-markdown/#syntax">Inline</a> or <a href="https://help.github.com/articles/creating-and-highlighting-code-blocks/">block</a> code snippets separate your descriptions from commands, helping users find your instructions quickly and making your troubleshooting examples clearer.</li>
          <li>GIFs and videos are nice ways to spinkle some humor into an otherwise bland README or quickly show your users exactly what to expect with a screencast (video of your screen as you run your program). It's worth noting that because of their security problems, iframes cannot be used for Github pages. Instead, add your GIF <a href="http://stackoverflow.com/questions/34341808/is-there-a-way-to-add-a-gif-to-a-markdown-file">as you would an image</a>. GIFs can also be hosted on imgur, gifly, etc. I found some <a href="https://schneems.com/post/41104255619/use-gifs-in-your-pull-request-for-good-not-evil"> detailed start-to-finish GIF-adding instuctions</a>, It seems that some cool kids have even gone so far as to <a href="https://github.com/rails/rails/pull/9001">include screencasts in their PRs</a>. Wowa.</li>
          <li><a href="http://shields.io/">Badges</a> can quickly give your users information about build status, dependancy checks, what version of a framework is used, and even where your project was built (the <a href="https://www.recurse.com/">Recurse Center</a> has it's <a href="https://swag.recurse.com/">own badges</a>, which many participants put on their projects with pride). Most badges are added by copy-pasting some badge-creating HTML. However, some languages have entire libraries of badges (here are <a href="https://github.com/badges/poser">PHP's</a>, <a href="https://github.com/badges/buckler">GO's</a>, and <a href="https://github.com/badges/stability-badges">JS's</a>). Because these badges are informative, look rad, and making your own badge is easy with tools such as are provided by <a href="http://shields.io/#your-badge">Shields.io</a> and <a href="http://sam.pikesley.org/projects/badger/">badger</a>, badges have been cropping up everywhere, and <a href="https://github.com/badges/shields">some efforts are being made to standardize and simplify their text</a> so they can continue to be the speedy information providers we hope they will be.</li>
          <li>For those who :heart: a little :sparkles:, <a href="https://www.webpagefx.com/tools/emoji-cheat-sheet/">emojis</a> are also supported to help you make your docs more :art:-ful. :tada:
        </ul>
        </p>

        <p>
        <h5>Documentation as a thinking aid</h5>
        Get ready to write awesome docs can begin by practicing clear thinking while you code. Especially as I learn how to scope projects, I find that writing some form of documentation at every stage of the project helps me break functions into tasks and keep the "big picture" goals of the project in sight.<br/>For me, there are two ways to do this: 
        <ol>
          <li>At the beginning of a project create comments for each action your code needs to take. More than likely, you'll find that you have just described each of the functions you will need.</li> 
          <li>As you write each function, give yourself a docstring describing what the function does, including its inputs and outputs.</li>
        </ol> 
        For me, the comments are just an in-between step for me as I organize my thinking. Most folks remove these comments from their final product, but docstrings are always welcomed by future viewers of the program (including future you!).
        </p>
        <p>
        If you're using Python, docstrings are written at the opening of a function, class, or method and enclosed in triple quotations, like this: <code>""" Description of function here """</code>. Other languages support docstrings as well, including Lisp, Elixir, Clojure, Gherkin, and Julia (<a href="https://en.wikipedia.org/wiki/Docstring">see Wikipedia for examples</a>). Documenting individual functions allowed me to not only organize my thinking while I was planning the project, but if I put off my documentation until I was finished, I never found myself slumping in my chair and thinking <em>Wait, what is this actually doing?</em>. It's much easier to summarize something when you have an "outline" of docstrings in front of you!
        </p>

        <p>
        <h5>Doc Generation</h5>
        Generating your docs from comments and docstrings is a powerful way to jump-start your documentation. Many languages and frameworks <a href="https://github.com/PharkMillups/beautiful-docs#generating-docs">have their own tools avalible</a>, or your can explore something more generic like <a href="https://github.com/GitbookIO/gitbook">Gitbook</a>.
        </p>

        <p>
        <h5>Tools and Resources</h5>
        The <a href="https://media.readthedocs.org/pdf/write-the-docs/latest/write-the-docs.pdf">Write the Docs Documentation on Writing Documentation</a> (say that four times fast!) is a spirited guide that walks you through the paces with an emphasis on the "why" of each step. Definately worth a read (and probably <a href="https://twitter.com/writethedocs">a follow on the twitters</a> if you do that). 
        <br/><br/>
        The Drupal project <a href="https://www.drupal.org/node/2181737">has its own guidelines</a>, as do most larger opensource projects. Reading and getting a sense of what has worked for others (and thinking about what makes sense for you!) is the best way to make informed deicisions about what to include.
        <br/><br/>
        Grip is a tool that <a href="https://github.com/joeyespo/grip">allows you to view your documentation locally</a>. If you're a person who finds themselves committing to Github in order to view and then make additional changes to their Markdown, this is going to be a real time saver (and result in a much cleaner commit history)!
        <br/><br/>
        The <a href="https://github.com/PharkMillups/beautiful-docs">beautiful-docs repo</a> has its own list of excellent docs and resources to aid doc creation.
        <br/><br/>
        <NAME>'s <a href="https://opensource.com/business/15/5/write-better-docs">call for better docs</a> crititcs examples of some of the best documenation out there and is definately worth a read. I note his position in Apache Software Foundation and that they have some of the best documentation I've seen (here's <a href="http://svn.apache.org/repos/asf/httpd/httpd/trunk/README">an example</a>). 
        </p>

        <p>
        Best of luck with the communication side of your programmin' and go out into the world and write some fab docs!
        </p>

      </section>
      <footer>
        <a href="http://twitter.com/veronica_hanus"><img src="../../../../img/twitter-wrap.png" alt="Twitter Logo" class="social-icon"></a>
        <a href="https://www.linkedin.com/in/veronicahanus"><img src="../../../../img/linkedin-wrap.png" alt="Twitter Logo" class="social-icon"></a>
        <p>&copy; & &#x2661 2017 <NAME>.</p>
      </footer>
    </div>
  </body>
</html><commit_msg>add image of README headings, made wording changes suggested by @dhanus<commit_after>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:fb="http://ogp.me/ns/fb#">
  <head>
    <meta charset="utf-8">
    <link rel="icon" href="../../../../img/favicon.png" type="image/x-icon">
    <meta property="og:image" content="img/veronica.jpg" />
    <title><NAME> | Everything is Awesome</title>
    <link rel="stylesheet" href="../../../../css/normalize.css">
    <link href='https://fonts.googleapis.com/css?family=Changa+One|Open+Sans:300,400,400italic,700,700italic,800' rel='stylesheet' type='text/css'>
    <link rel="stylesheet" href="../../../../css/main.css">
    <link rel="stylesheet" href="../../../../css/responsive.css">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
  </head>
  <body>
    <header>
      <a href="index.html" id="logo">
        <h1><NAME></h1>
        <h2>{ learning and writing }</h2>
      </a>
      <nav>
        <ul>
          <li><a href="../../../../index.html">Portfolio</a></li>
          <li><a href="../../../../blog.html" class="selected">Blog</a></li>
          <li><a href="../../../../about.html">About</a></li>
          <li><a href="../../../../contact.html">Contact</a></li>
        </ul>
      </nav>
    </header>
    <div id="wrapper">
      <section>
        <h3>Writing READMEs that will make future you happy</h3>
        <h5>March 6, 2017</h5>

        <br/>

        <p>
        Most of us have struggled to decide what to include when documenting our projects. Whether you are posting your first project to a repository and aren't sure how much to share about your program or you are improving documentation of an existing project to encourage others to contribute, staring at an empty README file can make us feel like we don't know where to start. I've made this guide to help you get jump-started. 
        </p>

        <p>
        <h5>What makes a README?</h5>
        Let's not sweat the Markdown, the flashy demos and screenshots, or the badges just yet. Good READMEs are about <a href="https://robots.thoughtbot.com/how-to-write-a-great-readme">clear writing</a> - clearly stating what problem your program solves, it's use, and (if you're looking for contributors) ways of getting folks familiar and able to jump on board - than they are about all the flashy "extras". Let's go back to our sixth-grader-starting-essay selves for a moment and make ourselves an outline.
        </p>

        <p>
        <center><img src="https://github.com/vzhz/vzhz.github.io/blob/a9e01b6c516d9f785ebbe63c2f69bf850b8e320c/blog/2017/03/06/Example_README_headings.png?raw=true" width="400" height="600" alt="screenshot of a README with the Introduction, Requirements, and Installation headings circled in red with the label 'All the information you need for a simple program'"></center>
        </p>

        <p>
        <h5>Core Components</h5>
        You should always include an <b>introduction</b> to the project (and the problem it solves), list any programs or modules your user will need to have as <b>requirements</b>, and <b>installation</b> instructions. Most READMEs include troubleshooting information and a call to action if the author is hoping for contributors. Remember your goal: You are providing information to help someone use or improve your code. What do they need?
        </p>

        <p>
        In the beginning, most projects have one contributor <a href="https://www.youtube.com/watch?v=TdrEmZ35fxc">('tis I)</a>, and I learned that the READMEs that other folks found the most helpful were the ones that I had written not for an imagined future user, but for my future self. If I were to rediscover this project three years from now, what would help me start using it again? What would help me make my first commit after being away from the code (and the problem it solves) for so long? These questions guide the first draft of every README I write.
        </p>

        <p>
        <h5>Putting your best foot forward</h5>
        Even if you can hum along with every line of the Lancelot's self-absorbed opening song in Camelot, you recognize that writing code is more exciting when it's used and appreciated by others. It's now time to step outside your own head, put your "user hat" on, and think about why someone might want to use your project. What will they wonder when they stumble on your README? I usually have a friend read my first draft over and ask them what they learned about my project and I adjust from there. 
        </p>
        <p>
        You can take the "have a friend read it" approach one step further by attending sprints (<a href=”https://en.wikipedia.org/wiki/Sprint_(software_development)”>project-centered work parties</a>) or "docathons" (hackathons focused on documentation) that support other open source projects. I've found that reviewing other projects' documentation by following their instructions for contributing, will teach you a lot about what your own first-time contributors will benefit from! "Taking a walk in your contributors shoes" is an essential step toward becoming a compassionate documentation writer.
        <!-- Where can I suggest people go to hear about docathons? First thing that comes to mind is the write the docs twitter (or their local chapter's twitter) but what else? -->
        </p>
        <p>
        If you can throw in a little humor, most readers will appreciate it provided all the important elements of the README are still easy to find. This <a href="https://github.com/jrbl/kegs">version of the game "bottles and kegs"</a> was a project I stumbled upon months ago and it still gives me the chuckles.

        <p>
        As you become more comfortable with your writing, you can investigate using visuals to inform your reader about your project.<br/> 
        There are many options:
        <ul>
          <li><a href="https://github.com/vzhz/friendly_terminal">Screenshots</a> allow potential users to preview your program's results and inspire confidence. You can add them to your document as you would an image, with <code>![text to show on rollover](https://github.com/your-name/your-repo/your-image)</code>.</li>
          <li><a href="https://guides.github.com/features/mastering-markdown/#syntax">Inline</a> or <a href="https://help.github.com/articles/creating-and-highlighting-code-blocks/">block</a> code snippets separate your descriptions from commands, helping users find your instructions quickly and making your troubleshooting examples clearer.</li>
          <li>GIFs and videos are nice ways to sprinkle some humor into an otherwise bland README or quickly show your users exactly what to expect with a screencast (video of your screen as you run your program). Notably, because of their security problems, iframes cannot be used for Github pages. Instead, add your GIF <a href="http://stackoverflow.com/questions/34341808/is-there-a-way-to-add-a-gif-to-a-markdown-file">as you would an image</a>. GIFs can also be hosted on imgur, gifly, etc. I found some <a href="https://schneems.com/post/41104255619/use-gifs-in-your-pull-request-for-good-not-evil"> detailed start-to-finish GIF-adding instuctions</a>, It seems that some cool kids have even gone so far as to <a href="https://github.com/rails/rails/pull/9001">include screencasts in their PRs</a>. Wowa.</li>
          <li><a href="http://shields.io/">Badges</a> can quickly give your users information about build status, dependency checks, what version of a framework is used, and even where your project was built (the <a href="https://www.recurse.com/">Recurse Center</a> has it's <a href="https://swag.recurse.com/">own badges</a>, which many participants put on their projects with pride). Most badges are added by copy-pasting some badge-creating HTML. However, some languages have entire libraries of badges (here are <a href="https://github.com/badges/poser">PHP's</a>, <a href="https://github.com/badges/buckler">GO's</a>, and <a href="https://github.com/badges/stability-badges">JS's</a>). Because these badges are informative, look rad, and making your own badge is easy with tools such as are provided by <a href="http://shields.io/#your-badge">Shields.io</a> and <a href="http://sam.pikesley.org/projects/badger/">badger</a>, badges have been cropping up everywhere, and <a href="https://github.com/badges/shields">some efforts are being made to standardize and simplify their text</a> so they can continue to be the speedy information providers we hope they will be.</li>
          <li>For those who :heart: a little :sparkles:, <a href="https://www.webpagefx.com/tools/emoji-cheat-sheet/">emojis</a> are also supported to help you make your docs more :art:-ful. :tada:
        </ul>
        </p>

        <p>
        <h5>Documentation as a thinking aid</h5>
        Get ready to write awesome docs can begin by practicing clear thinking while you code. Especially as I learn how to scope projects, I find that writing some form of documentation at every stage of the project helps me break functions into tasks and keep the "big picture" goals of the project in sight.<br/>For me, there are two ways to do this: 
        <ol>
          <li>At the beginning of a project, create comments for each action your code needs to take. You'll likely find that you have just described each of the functions you will need.</li> 
          <li>As you write each function, give yourself a docstring describing what the function does, including its inputs and outputs.</li>
        </ol> 
        These comments are an important step for me as I organize my thinking. Most folks remove these comments from their final product, but future viewers always welcome docstrings (including future you!).
        </p>
        <p>
        If you're using Python, docstrings are written in the first line of a function, class, or method and enclosed in triple quotations, like this: <code>""" Description of function here """</code>. Other languages support docstrings as well, including Lisp, Elixir, Clojure, Gherkin, and Julia (<a href="https://en.wikipedia.org/wiki/Docstring">see Wikipedia for examples</a>). Documenting individual functions allowed me to not only organize my thinking while I was planning the project, but if I put off my documentation until I was finished, I never found myself slumping in my chair and thinking <em>Wait, what is this actually doing?</em>. It's much easier to summarize something when you have an "outline" of docstrings in front of you!
        </p>

        <p>
        <h5>Doc Generation</h5>
        Generating your docs from comments and docstrings is a powerful way to jumpstart your documentation. Many languages and frameworks <a href="https://github.com/PharkMillups/beautiful-docs#generating-docs">have their own tools available</a>, or your can explore something more generic like <a href="https://github.com/GitbookIO/gitbook">Gitbook</a>.
        </p>

        <p>
        <h5>Tools and Resources</h5>
        The <a href="https://media.readthedocs.org/pdf/write-the-docs/latest/write-the-docs.pdf">Write the Docs Documentation on Writing Documentation</a> (say that four times fast!) is a spirited guide that walks you through the paces with an emphasis on the "why" of each step. Definitely worth a read (and probably <a href="https://twitter.com/writethedocs">a follow on the twitters</a> if you do that). 
        <br/><br/>
        The Drupal project <a href="https://www.drupal.org/node/2181737">has its own guidelines</a>, as do most larger open source projects. Reading and getting a sense of what has worked for others (and thinking about what makes sense for you!) is the best way to make informed decisions about what to include.
        <br/><br/>
        Grip is a tool that <a href="https://github.com/joeyespo/grip">allows you to view your documentation locally</a>. If you find yourself committing to Github in order to view and then make additional changes to your Markdown, this is going to be a real time saver (and result in a much cleaner commit history)!
        <br/><br/>
        The <a href="https://github.com/PharkMillups/beautiful-docs">beautiful-docs repo</a> has its own list of excellent docs and resources to aid doc creation.
        <br/><br/>
        <NAME>'s <a href="https://opensource.com/business/15/5/write-better-docs">call for better docs</a> critiques examples of some of the best documenation out there, and it is definitely worth a read. He is involved with the Apache Software foundation, which has some of the best documentation I've seen (here's <a href="http://svn.apache.org/repos/asf/httpd/httpd/trunk/README">an example</a>). 
        </p>

        <p>
        Best of luck with the communication side of your programmin' and go out into the world and write some fab docs!
        </p>

      </section>
      <footer>
        <a href="http://twitter.com/veronica_hanus"><img src="../../../../img/twitter-wrap.png" alt="Twitter Logo" class="social-icon"></a>
        <a href="https://www.linkedin.com/in/veronicahanus"><img src="../../../../img/linkedin-wrap.png" alt="Twitter Logo" class="social-icon"></a>
        <p>&copy; & &#x2661 2017 <NAME>.</p>
      </footer>
    </div>
  </body>
</html>
{'fraction_non_alphanumeric': 0.11030817465779613, 'fraction_numerical': 0.008602890571231933, 'mean_word_length': 3.375209100033456, 'pattern_counts': {'":': 0, '<': 417, '<?xml version=': 0, '>': 417, 'https://': 56, 'lorem ipsum': 0, 'www.': 12, 'xml': 4}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '231412', 'n_tokens_mistral': 7489, 'n_tokens_neox': 7057, 'n_words': 3178}