├── .gitignore ├── pages ├── .gemrc ├── github-repo-checklist.md ├── naming-your-project.md ├── writing-clear-and-concise-issues.md ├── writing-the-repo-description.md ├── using-the-wiki.md └── making-readmes-readable.md ├── assets └── css │ └── styles.scss ├── images ├── .DS_Store ├── wiki1.png ├── wiki2.png ├── wiki3.png ├── wiki4.png ├── wiki5.png ├── wiki6.png ├── wiki7.png ├── descriptions-on-github.png └── method-cards-description.png ├── Gemfile ├── copy-template ├── .about.yml ├── CONTRIBUTING.md ├── LICENSE.md ├── go ├── _config.yml ├── Gemfile.lock ├── index.md └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | _site/ 2 | .sass-cache/ 3 | .DS_store 4 | .*.swp 5 | -------------------------------------------------------------------------------- /pages/.gemrc: -------------------------------------------------------------------------------- 1 | install: --no-ri --no-rdoc 2 | update: --no-ri --no-rdoc -------------------------------------------------------------------------------- /assets/css/styles.scss: -------------------------------------------------------------------------------- 1 | --- 2 | --- 3 | 4 | @import "guides_style_18f"; 5 | -------------------------------------------------------------------------------- /images/.DS_Store: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/18F/open-source-guide/HEAD/images/.DS_Store -------------------------------------------------------------------------------- /images/wiki1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/18F/open-source-guide/HEAD/images/wiki1.png -------------------------------------------------------------------------------- /images/wiki2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/18F/open-source-guide/HEAD/images/wiki2.png -------------------------------------------------------------------------------- /images/wiki3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/18F/open-source-guide/HEAD/images/wiki3.png -------------------------------------------------------------------------------- /images/wiki4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/18F/open-source-guide/HEAD/images/wiki4.png -------------------------------------------------------------------------------- /images/wiki5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/18F/open-source-guide/HEAD/images/wiki5.png -------------------------------------------------------------------------------- /images/wiki6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/18F/open-source-guide/HEAD/images/wiki6.png -------------------------------------------------------------------------------- /images/wiki7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/18F/open-source-guide/HEAD/images/wiki7.png -------------------------------------------------------------------------------- /images/descriptions-on-github.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/18F/open-source-guide/HEAD/images/descriptions-on-github.png -------------------------------------------------------------------------------- /images/method-cards-description.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/18F/open-source-guide/HEAD/images/method-cards-description.png -------------------------------------------------------------------------------- /Gemfile: -------------------------------------------------------------------------------- 1 | source 'https://rubygems.org' 2 | 3 | gem 'jekyll' 4 | gem 'rouge' 5 | gem 'go_script' 6 | 7 | group :jekyll_plugins do 8 | gem 'guides_style_18f' 9 | end 10 | -------------------------------------------------------------------------------- /copy-template: -------------------------------------------------------------------------------- 1 | #! /bin/bash 2 | 3 | usage() { 4 | echo "Usage: $0 [path to target repository]" 5 | exit 1 6 | } 7 | 8 | if [ $# -ne 1 ]; then 9 | echo "Error: Exactly one target repository must be specified" 10 | usage 11 | fi 12 | 13 | if [ ! -d $1 ]; then 14 | echo "Error: $1 is not a directory" 15 | usage 16 | fi 17 | 18 | # Hack per: 19 | # http://stackoverflow.com/questions/4774054/reliable-way-for-a-bash-script-to-get-the-full-path-to-itself 20 | pushd $(dirname $0) >/dev/null 21 | TEMPLATE_ROOT=$(pwd -P) 22 | popd >/dev/null 23 | 24 | PATH=/usr/bin 25 | TARGET=$(echo "$1/" | sed 's#//$#/#') 26 | rsync -av --exclude .DS_Store $TEMPLATE_ROOT/{_includes,_layouts,assets} $TARGET 27 | -------------------------------------------------------------------------------- /.about.yml: -------------------------------------------------------------------------------- 1 | --- 2 | name: open_source 3 | full_name: Open Source Working Group 4 | type: docs 5 | owner_type: "working-group" 6 | status: active 7 | testable: false 8 | description: > 9 | We support 18F better practicing and implementing open source. 10 | stage: live 11 | licenses: 12 | wg-open_source: 13 | name: Public Domain (CC0) 14 | url: https://creativecommons.org/publicdomain/zero/1.0/ 15 | links: 16 | - url: https://pages.18f.gov/open-source-guide/ 17 | text: 18F Open Source Guide 18 | - url: https://pages.18f.gov/open-source-program/ 19 | text: 18F Open Source Program 20 | - url: https://github.com/18F/open-source-policy 21 | text: 18F Open Source Policy 22 | team: 23 | - github: brittag 24 | role: lead 25 | - github: adrianwebb 26 | role: lead 27 | - github: gbinal 28 | - github: afeld 29 | -------------------------------------------------------------------------------- /pages/github-repo-checklist.md: -------------------------------------------------------------------------------- 1 | --- 2 | permalink: /github-repo-checklist/ 3 | title: GitHub repo checklist 4 | --- 5 | 6 | ## Name 7 | 8 | * Is the name clear and descriptive? 9 | 10 | ## Description 11 | 12 | If your project is active, does your description: 13 | 14 | * Let someone know exactly what’s in the repo? 15 | * Describe the code and the project in a sentence or two? 16 | 17 | If your project is no longer active, does your description: 18 | 19 | * Note it’s no longer active by placing the word DEPRECATED in front of the description? 20 | * Indicate where people can find the active version of the project, if one exists? 21 | 22 | ## README 23 | 24 | Does your README answer the following questions: 25 | 26 | * What is the project? 27 | * How does someone develop, use, and test the code? 28 | * How can people become more involved? 29 | * What is the licensing for this project? 30 | * How do people contact the developers or ask a question? 31 | 32 | ## Issues 33 | 34 | Are your issues: 35 | 36 | * Written clearly and in the style of a user story? 37 | * Labeled clearly with the type of help you need? 38 | * Detailed with additional documentation as needed? 39 | -------------------------------------------------------------------------------- /pages/naming-your-project.md: -------------------------------------------------------------------------------- 1 | --- 2 | permalink: /naming-your-project/ 3 | title: Naming your project 4 | --- 5 | 6 | ### Before naming a project, think ‘Is this easy to understand?’ 7 | 8 | To help users find and recognize your project, we recommend using descriptive names that describe what your project does. You should avoid acronyms and clever names/puns as those can make it hard to search for projects. 9 | 10 | You should also do a quick search on the web for your project's name to make sure that name isn't already being used by other software or services, even if it's used in a different space, as it can be confusing for new users. It’s also important to check with your communications team before naming a project so that it can be cleared, if need be. 11 | 12 | For example, if you were creating a template your coworkers could use to create guides, a good name for the repo might be *guides-template*. Bad names might include *the-unnamed-project-that-makes-it-easy-to-build-stuff*, *temp-latte*, or *guidestar*. 13 | 14 | Within the context of GitHub, the name of your project will always be placed alongside its organizational owner's name. So it's unnecessary to combine the two: instead of naming a project *my-organization-foo*, you can simply name it *foo*. 15 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | ## Welcome! 2 | 3 | We're so glad you're thinking about contributing to an 18F open source project! If you're unsure about anything, just ask -- or submit the issue or pull request anyway. The worst that can happen is you'll be politely asked to change something. We love all friendly contributions. 4 | 5 | We want to ensure a welcoming environment for all of our projects. Our staff follow the [18F Code of Conduct](https://github.com/18F/code-of-conduct/blob/master/code-of-conduct.md) and all contributors should do the same. 6 | 7 | We encourage you to read this project's CONTRIBUTING policy (you are here), its [LICENSE](LICENSE.md), and its [README](README.md). 8 | 9 | If you have any questions or want to read more, check out the [18F Open Source Policy GitHub repository]( https://github.com/18f/open-source-policy), or just [shoot us an email](mailto:18f@gsa.gov). 10 | 11 | ## Public domain 12 | 13 | This project is in the public domain within the United States, and 14 | copyright and related rights in the work worldwide are waived through 15 | the [CC0 1.0 Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/). 16 | 17 | All contributions to this project will be released under the CC0 18 | dedication. By submitting a pull request, you are agreeing to comply 19 | with this waiver of copyright interest. 20 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | As a work of the United States government, this project is in the public domain within the United States. 2 | 3 | Additionally, we waive copyright and related rights in the work worldwide through the CC0 1.0 Universal public domain dedication. 4 | 5 | ## CC0 1.0 Universal summary 6 | 7 | This is a human-readable summary of the [Legal Code (read the full text)](https://creativecommons.org/publicdomain/zero/1.0/legalcode). 8 | 9 | ### No copyright 10 | 11 | The person who associated a work with this deed has dedicated the work to the public domain by waiving all of his or her rights to the work worldwide under copyright law, including all related and neighboring rights, to the extent allowed by law. 12 | 13 | You can copy, modify, distribute and perform the work, even for commercial purposes, all without asking permission. 14 | 15 | ### Other information 16 | 17 | In no way are the patent or trademark rights of any person affected by CC0, nor are the rights that other persons may have in the work or in how the work is used, such as publicity or privacy rights. 18 | 19 | Unless expressly stated otherwise, the person who associated a work with this deed makes no warranties about the work, and disclaims liability for all uses of the work, to the fullest extent permitted by applicable law. When using or citing the work, you should not imply endorsement by the author or the affirmer. 20 | -------------------------------------------------------------------------------- /go: -------------------------------------------------------------------------------- 1 | #! /usr/bin/env ruby 2 | 3 | require 'English' 4 | 5 | Dir.chdir File.dirname(__FILE__) 6 | 7 | def try_command_and_restart(command) 8 | exit $CHILD_STATUS.exitstatus unless system command 9 | exec RbConfig.ruby, *[$PROGRAM_NAME].concat(ARGV) 10 | end 11 | 12 | begin 13 | require 'bundler/setup' if File.exist? 'Gemfile' 14 | rescue LoadError 15 | try_command_and_restart 'gem install bundler' 16 | rescue SystemExit 17 | try_command_and_restart 'bundle install' 18 | end 19 | 20 | begin 21 | require 'go_script' 22 | rescue LoadError 23 | try_command_and_restart 'gem install go_script' unless File.exist? 'Gemfile' 24 | abort "Please add \"gem 'go_script'\" to your Gemfile" 25 | end 26 | 27 | require 'guides_style_18f' 28 | 29 | extend GoScript 30 | check_ruby_version '2.1.5' 31 | 32 | command_group :dev, 'Development commands' 33 | 34 | def_command :update_nav, 'Update the \'navigation:\' data in _config.yml' do 35 | GuidesStyle18F.update_navigation_configuration Dir.pwd 36 | end 37 | 38 | def_command :update_theme, 'Update the guides_style_18f gem' do 39 | exec_cmd 'bundle update --source guides_style_18f' 40 | end 41 | 42 | def_command :update_gems, 'Update Ruby gems' do |gems| 43 | update_gems gems 44 | end 45 | 46 | def_command :serve, 'Serve the site at localhost:4000' do 47 | serve_jekyll 48 | end 49 | 50 | def_command :build, 'Build the site' do 51 | build_jekyll 52 | end 53 | 54 | execute_command ARGV 55 | -------------------------------------------------------------------------------- /pages/writing-clear-and-concise-issues.md: -------------------------------------------------------------------------------- 1 | --- 2 | permalink: /writing-clear-and-concise-issues/ 3 | title: Writing clear and concise issues 4 | --- 5 | 6 | Tasks that need to be completed or discussed are added to repos as issues. 7 | 8 | If you want outside contributors to help work on your project, it’s important to write clear issues that detail what people can work on. You can also [use labels](https://github.com/18F/Midas/labels) to distinguish issues and sort them into categories. For example, [here are all of the open issues](https://github.com/18F/Midas/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3Aquestion) on the Midas project that are listed as questions. 9 | 10 | It's particularly helpful to use the ‘Help Wanted’ label for tasks or questions you need help with. ([Examples.](https://github.com/18F/midas/labels/help%20wanted)) Why? There are other sites, like [Govcode](https://www.govcode.org/) and Code for America’s [Civic Tech Issue Finder](https://www.codeforamerica.org/geeks/civicissues), which surface issues that have been labeled ‘Help Wanted’ so people can jump in and help. You can also use the ‘Beginner Friendly’ label to specifically note tasks that are suitable for beginners. 11 | 12 | When writing an issue, it's often helpful to craft it in terms of a user story because it frames the task in terms of a user need. User stories are framed as follows: “As an X, I want to do Y because Z.” [Here is an example](https://github.com/18F/midas/issues/718) of an issue framed as a user story. 13 | -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | markdown: redcarpet 2 | name: 18F Open Source Style Guide 3 | exclude: 4 | - CONTRIBUTING.md 5 | - Gemfile 6 | - Gemfile.lock 7 | - LICENSE.md 8 | - README.md 9 | - go 10 | 11 | permalink: pretty 12 | highlighter: rouge 13 | 14 | sass: 15 | style: :compressed 16 | 17 | # Author/Organization info to be displayed in the templates 18 | author: 19 | name: 18F 20 | url: https://18f.gsa.gov 21 | 22 | # Point the logo URL at a file in your repo or hosted elsewhere by your organization 23 | logourl: /assets/img/18f-logo.png 24 | logoalt: 18F logo 25 | 26 | # Navigation 27 | # List links that should appear in the site sidebar here 28 | navigation: 29 | - text: Introduction 30 | url: index.html 31 | internal: true 32 | - text: Naming your project 33 | url: naming-your-project/ 34 | internal: true 35 | - text: Making repo descriptions short and clear 36 | url: writing-the-repo-description/ 37 | internal: true 38 | - text: Making READMEs readable 39 | url: making-readmes-readable/ 40 | internal: true 41 | - text: Writing clear and concise issues 42 | url: writing-clear-and-concise-issues/ 43 | internal: true 44 | - text: Best practices for using the wiki 45 | url: using-the-wiki/ 46 | internal: true 47 | - text: GitHub repo checklist 48 | url: github-repo-checklist/ 49 | internal: true 50 | 51 | repos: 52 | - name: 18F Open Source Style Guide 53 | description: Main repository 54 | url: https://github.com/18F/open-source-guide 55 | 56 | back_link: 57 | url: "https://pages.18f.gov/guides/" 58 | text: Read more 18F Guides 59 | 60 | defaults: 61 | - 62 | scope: 63 | path: "" 64 | values: 65 | layout: "guides_style_18f_default" 66 | -------------------------------------------------------------------------------- /Gemfile.lock: -------------------------------------------------------------------------------- 1 | GEM 2 | remote: https://rubygems.org/ 3 | specs: 4 | blankslate (2.1.2.4) 5 | celluloid (0.16.0) 6 | timers (~> 4.0.0) 7 | classifier-reborn (2.0.3) 8 | fast-stemmer (~> 1.0) 9 | coffee-script (2.4.1) 10 | coffee-script-source 11 | execjs 12 | coffee-script-source (1.9.1.1) 13 | colorator (0.1) 14 | execjs (2.5.2) 15 | fast-stemmer (1.0.2) 16 | ffi (1.9.9) 17 | go_script (0.1.4) 18 | bundler (~> 1.10) 19 | safe_yaml (~> 1.0) 20 | guides_style_18f (0.1.1) 21 | jekyll (~> 2.5) 22 | rouge (~> 1.9) 23 | sass (~> 3.4) 24 | hitimes (1.2.2) 25 | jekyll (2.5.3) 26 | classifier-reborn (~> 2.0) 27 | colorator (~> 0.1) 28 | jekyll-coffeescript (~> 1.0) 29 | jekyll-gist (~> 1.0) 30 | jekyll-paginate (~> 1.0) 31 | jekyll-sass-converter (~> 1.0) 32 | jekyll-watch (~> 1.1) 33 | kramdown (~> 1.3) 34 | liquid (~> 2.6.1) 35 | mercenary (~> 0.3.3) 36 | pygments.rb (~> 0.6.0) 37 | redcarpet (~> 3.1) 38 | safe_yaml (~> 1.0) 39 | toml (~> 0.1.0) 40 | jekyll-coffeescript (1.0.1) 41 | coffee-script (~> 2.2) 42 | jekyll-gist (1.2.1) 43 | jekyll-paginate (1.1.0) 44 | jekyll-sass-converter (1.3.0) 45 | sass (~> 3.2) 46 | jekyll-watch (1.2.1) 47 | listen (~> 2.7) 48 | kramdown (1.7.0) 49 | liquid (2.6.2) 50 | listen (2.10.1) 51 | celluloid (~> 0.16.0) 52 | rb-fsevent (>= 0.9.3) 53 | rb-inotify (>= 0.9) 54 | mercenary (0.3.5) 55 | parslet (1.5.0) 56 | blankslate (~> 2.0) 57 | posix-spawn (0.3.11) 58 | pygments.rb (0.6.3) 59 | posix-spawn (~> 0.3.6) 60 | yajl-ruby (~> 1.2.0) 61 | rb-fsevent (0.9.5) 62 | rb-inotify (0.9.5) 63 | ffi (>= 0.5.0) 64 | redcarpet (3.3.2) 65 | rouge (1.9.0) 66 | safe_yaml (1.0.4) 67 | sass (3.4.15) 68 | timers (4.0.1) 69 | hitimes 70 | toml (0.1.2) 71 | parslet (~> 1.5.0) 72 | yajl-ruby (1.2.1) 73 | 74 | PLATFORMS 75 | ruby 76 | 77 | DEPENDENCIES 78 | go_script 79 | guides_style_18f 80 | jekyll 81 | rouge 82 | 83 | BUNDLED WITH 84 | 1.10.6 85 | -------------------------------------------------------------------------------- /index.md: -------------------------------------------------------------------------------- 1 | --- 2 | permalink: / 3 | title: Introduction 4 | --- 5 | 6 | This guide helps people document code repositories so that they're easy to use and understand. In each section, we outline our strategies for making sure that our code repositories are clear, accessible, and user-friendly. 7 | 8 | It’s important to make sure our documentation is clear both for internal and external audiences. As our team expands, we want our new employees to easily find and use our existing codebases. 9 | 10 | It's also really important if we want to make outside contributors feel welcome or have outside organizations fork and use our code. ([And we do!](https://github.com/18F/open-source-policy/blob/master/policy.md)) Explaining what a project is, why it's important, and how people can help ensures that people can fork and adapt our projects. 11 | 12 | (Fork means to copy the code that exists over to your own repo, or repository of code, so that you can adapt or use it as needed.) 13 | 14 | This guide also contains a checklist we created that helps ensure our repos are clear, accessible, and user-friendly. Some terminology used may be GitHub-specific, but the concepts are applicable regardless of your version control system or platform. We wrote it so that both non-coders and coders can understand it. (If something is not clear, please let us know.) 15 | 16 | We’re sharing it because it we think it’s helpful for lots of organizations, including our own. We know that many of our repos don’t conform to this exact style. By articulating a specific style, we hope this document will also help us improve our own practices. 17 | 18 | 19 | ## How to use this guide 20 | 21 | We created this guide for reference on an as-needed basis. It’s here when you’re wondering how to describe a repo, for instance, or when you’re wondering how to create a friendly, informational tone when writing issues for users. 22 | 23 | To this end, we’ve structured the guide into descriptively named sections. Browse our table of contents to find the topic you’re looking for. 24 | 25 | Most importantly, we encourage you to make a copy of this document and adapt it to your organizational needs. This guide is just that: a guide. It’s not meant to provide the final opinion on any of the topics discussed. If a certain section isn’t relevant to you and your team, delete it. And if you feel the guide is missing a section, by all means, add it. This guide is yours to use, and we trust you’ll update it in the ways that best suit you. 26 | -------------------------------------------------------------------------------- /pages/writing-the-repo-description.md: -------------------------------------------------------------------------------- 1 | --- 2 | permalink: /writing-the-repo-description/ 3 | title: Making repo descriptions short and clear 4 | --- 5 | 6 | The description of a repo tells the public what is contained in the repo itself. If you have multiple repositories for the same project, it's better to describe what is contained in the repo itself instead of describing the project. 7 | 8 | Repo descriptions should be clear, concise, and descriptive. Descriptions are listed under each repository title on an organization’s GitHub page. Anyone who scans the GitHub page should be able to determine what a repo does, just by looking at the description. 9 | 10 | For example, let's look at the description of some 18F projects. 11 | 12 | 18F GitHub repositories and descriptions, which are written below 13 | 14 | The description for the repo [*domain-scan*](https://github.com/18F/domain-scan) is "Scan domains for various web things, like HTTP/HTTPs configuration." 15 | 16 | The description for the repo [*midas-open-opportunities*](https://github.com/18F/midas-open-opportunities) is "Digital Services Innovation Center's Open Opportunities on the Midas Platform." 17 | 18 | And the description for the repo [*pulse*](https://github.com/18F/pulse) is "How the .gov space is doing at best practices and federal requirements." 19 | 20 | Each of these descriptions is clear and tells the user exactly what she or he will find when opening the repo. 21 | 22 | Screenshot of Description of Method Cards repository. Description: 'An initial collection of design methods, which includes general descriptions, how-tos, and how such methods can be put into practice for government projects 23 | 24 | It’s sometimes hard to think of a complete description of the repo in one or two sentences. An easy way to come up with a good description is to think ‘How would I explain what this project does in one or two sentences to someone at a dinner party?’ Those are the sentences you want to write down as your repo description. Before you publish, it also helps to run your description by someone who doesn’t work on your team. Do they have any suggestions? 25 | 26 | ## If a project isn’t active, make that clear 27 | 28 | If your repo is not in active development, it’s helpful to let users know this so they don’t make contributions to a non-active repository. We suggest adding the word DEPRECATED before your repo description. [Here is an example](https://github.com/18F/Mario) of a deprecated repo. 29 | 30 | ## Add a website next to the description, when it exists 31 | 32 | Next to the description of a repository, there's a spot to add a link to a website. You should always add a link to a website, if it exists. 33 | 34 | 35 | -------------------------------------------------------------------------------- /pages/using-the-wiki.md: -------------------------------------------------------------------------------- 1 | --- 2 | permalink: /using-the-wiki/ 3 | title: Best practices for using the wiki 4 | --- 5 | 6 | Some of our teammates recommend turning off a repo's Wiki unless you have a proactive use for it. But there are many ways to use a Wiki and use it well. 7 | 8 | If you’re using GitHub, you can enable a wiki on every GitHub repo by going to its settings and checking the ‘Wikis’ box under ‘Features.’ 9 | 10 | Turn the wiki feature on by going to settings and clicking on Wikis under the box labeled 'Features' 11 | 12 | What does this get you? Tons! You can now put all the great information that would have made your README way too long and complicated into separate, clear pages. For example, the 18f.gsa.gov team uses the wiki for all their “how to do this” work, and catalogues items like decisions on which blogging tags to use across our sites. 13 | 14 | This is the 18F site wiki, which catalogs how to use tags on their platforms. 15 | 16 | Another really great use for the wiki is to house your product roadmap and user research goals. 18F’s Michelle Hertzfeld is a huge proponent of keeping these documents in the repo with the codebase so they’re easy to find, share and get feedback on. 17 | 18 | A screenshot of the roadmap for USEITI website, which is located in a wiki 19 | 20 | ## Tracking user research on GitHub 21 | 22 | Speaking of user research, some of our project teams also like to keep their research process and findings in the repo along with the code. This helps keep all project documentation together in one place and also makes sure that we’re not only *building* in the open, but also *researching* in the open. This way, team members, and anyone else who is interested, can track the research that went into project decisions. 23 | 24 | Naturally, this does not include posting confidential interviews with people or anything else that should not be shared. What it includes are things like: 25 | 26 | * Research plans 27 | * Interview scripts 28 | * Summarized research findings 29 | 30 | One way to do this is to create an “orphan branch” to keep your research in. An orphan branch is a branch that you name that sits within the repo. Creating an orphan branch lets you have a completely different file structure from the rest of the repo in that branch, and you can put all of your research within that branch, as follows: 31 | 32 | * First, create a new branch under branch:master and label it with a new name. Michelle chose research. ([Example](https://github.com/18F/doi-extractives-data/tree/research)) 33 | 34 | Create a new branch under branch:master 35 | 36 | * You are now on a branch of the repo, where you can store information. 37 | 38 | A screenshot of the research branch 39 | 40 | * Michelle stores information like user research for various sprints [in this repo](https://github.com/18F/doi-extractives-data/tree/research/research/sprint17). 41 | 42 | Screenshot of user research for Sprint 17 43 | 44 | * This makes it easy for others to [find and use the user research](https://github.com/18F/doi-extractives-data/blob/research/research/sprint17/sprint17_results.md), and remains within the project repo. 45 | 46 | Screenshot of usability tests conducted during Sprint 17 47 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ## 18F Open Source Style Guide 2 | 3 | 4 | This guide helps people document code repositories so that they're easy to use and understand. In each section, we outline our strategies for making sure that our code repositories are clear, accessible, and user-friendly. 5 | 6 | It’s important to make sure our documentation is clear both for internal and external audiences. As our team expands, we want our new employees to easily find and use our existing codebases. 7 | 8 | It's also really important if we want to make outside contributors feel welcome or have outside organizations fork and use our code. ([And we do!](https://github.com/18F/open-source-policy/blob/master/policy.md)) Explaining what a project is, why it's important, and how people can help ensures that people can fork and adapt our projects. 9 | 10 | (Fork means to copy the code that exists over to your own repo, or repository of code, so that you can adapt or use it as needed.) 11 | 12 | This guide also contains a checklist we created that helps ensure our repos are clear, accessible, and user-friendly. Some terminology used may be GitHub-specific, but the concepts are applicable regardless of your version control system or platform. We wrote it so that both non-coders and coders can understand it. (If something is not clear, please let us know.) 13 | 14 | We’re sharing it because it we think it’s helpful for lots of organizations, including our own. We know that many of our repos don’t conform to this exact style. By articulating a specific style, we hope this document will also help us improve our own practices. 15 | 16 | 17 | ## How to use this guide 18 | 19 | We created this guide for reference on an as-needed basis. It’s here when you’re wondering how to describe a repo, for instance, or when you’re wondering how to create a friendly, informational tone when writing issues for users. 20 | 21 | To this end, we’ve structured the guide into descriptively named sections. Browse our table of contents to find the topic you’re looking for. 22 | 23 | Most importantly, we encourage you to make a copy of this document and adapt it to your organizational needs. This guide is just that: a guide. It’s not meant to provide the final opinion on any of the topics discussed. If a certain section isn’t relevant to you and your team, delete it. And if you feel the guide is missing a section, by all means, add it by clicking 'edit this page' at the bottom of every page. This guide is yours to use, and we trust you’ll update it in the ways that best suit you. 24 | 25 | 26 | ### Public domain 27 | 28 | This project is in the worldwide [public domain](LICENSE.md). As stated in [CONTRIBUTING](CONTRIBUTING.md): 29 | 30 | > This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the [CC0 1.0 Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/). 31 | > 32 | > All contributions to this project will be released under the CC0 33 | >dedication. By submitting a pull request, you are agreeing to comply 34 | >with this waiver of copyright interest. 35 | 36 | 37 | ### How to run a local copy of this guide 38 | 39 | (Instructions adapted from the [18F Documentation Working Group](https://github.com/18F/wg-documentation).) 40 | 41 | You will need [Ruby](https://www.ruby-lang.org) ( > version 2.1.5 ). You may 42 | consider using a Ruby version manager such as 43 | [rbenv](https://github.com/sstephenson/rbenv) or [rvm](https://rvm.io/) to 44 | help ensure that Ruby version upgrades don't mean all your 45 | [gems](https://rubygems.org/) will need to be rebuilt. 46 | 47 | On OS X, you can use [Homebrew](http://brew.sh/) to install Ruby in 48 | `/usr/local/bin`, which may require you to update your `$PATH` environment 49 | variable: 50 | 51 | ```shell 52 | $ brew update 53 | $ brew install ruby 54 | ``` 55 | 56 | To serve the site locally: 57 | 58 | ```shell 59 | $ git clone git@github.com:18F/open-source-guide.git 60 | $ cd open-source-guide 61 | $ ./go serve 62 | ``` 63 | 64 | This will check that your Ruby version is supported, install the [Bundler 65 | gem](http://bundler.io/) if it is not yet installed, install all the gems 66 | needed by the template, and launch a running instance on 67 | `http://localhost:4000/`. (Make sure to include the trailing 68 | slash! The built-in Jekyll webserver doesn't redirect to it.) 69 | 70 | After going through these steps, run `./go` to see a list of available 71 | commands. The `serve` command is the most common for routine development. 72 | 73 | 74 | ### How to create your own guide 75 | 76 | This guide is based on the [DOCter template](https://github.com/cfpb/DOCter) created by the 77 | [Consumer Financial Protection Bureau](http://www.consumerfinance.gov/) (CFPB). Our canonical 78 | adaptation of DOCter is contained in the [18F Guides Template](https://pages.18f.gov/guides-template/). 79 | 80 | 81 | ### Contact us 82 | 83 | If you'd like to contact us, please create a GitHub issue or email 18F@gsa.gov. Thank you! 84 | -------------------------------------------------------------------------------- /pages/making-readmes-readable.md: -------------------------------------------------------------------------------- 1 | --- 2 | permalink: /making-readmes-readable/ 3 | title: Making READMEs readable 4 | --- 5 | 6 | Every repo contains a README, which is a document that is intended to explain, at first glance, what a project does and how to install or test the code. 7 | 8 | READMEs are really important because they’re the first item a user will see when encountering your code. Creating a readable README ensures that your co-workers and the public will be able to understand the intention of your program, install the software, and fork and adapt your projects. 9 | 10 | We find it helpful to think of the README as a guide to your code or project. It’s often helpful to create sections in the README for users to learn about the project. We recommend the following sections. 11 | 12 | ## A description of what the project is for. 13 | 14 | This should answer a short list of basic questions: 15 | 16 | * **What is this repo or project?** (You can reuse the repo description you used earlier because this section doesn’t have to be long.) 17 | * **How does it work?** 18 | * **Who will use this repo or project?** 19 | * **What is the goal of this project?** 20 | 21 | You likely have the answer to many of these questions in your head and have discussed them with your team. It's helpful to write them down for people who find your repository. Not only will it be easier for developers to know how to fork the project or become involved with the project, but it will be easy for non-coders to understand what the code is designed to do, and how they, too, can become involved. 22 | 23 | **Example:** The [README for 18F’s Midas project](https://github.com/18f/midas) starts out by answering the questions: 24 | 25 | * What is Midas? 26 | * How does Midas work? 27 | * Who uses Midas? 28 | * What is Midas’ goal? 29 | * How can your organization benefit from using Midas? 30 | 31 | ## Instructions for how to develop, use, and test the code. 32 | 33 | This should answer the question: **How do I get this project to work on my machine? How can I develop for this project?** We find it works really well if you follow a two-step approach to develop the content for this section: first, help someone setup the site who has never done it before, and then write down the exact instructions. Next, ask someone to follow those instructions and see if you’ve missed anything. 34 | 35 | Important: If relevant code changes, it’s important to test to ensure these instructions continue to work. We also recommend separating the sections for using a project versus developing for it. (More detailed instructions are located [in our guidelines](https://pages.18f.gov/open-source-program/pages/maintainer_guidelines/#usage-documentation) for writing documentation for users, contributors, and developers.) 36 | 37 | **Example:** The README for analytics.usa.gov contains detailed instructions for [developing the site](https://github.com/18f/analytics.usa.gov#setup) and [deploying the site](https://github.com/18f/analytics.usa.gov#deploying-to-staging-18f-specific). 38 | 39 | ## Instructions for how people can help. 40 | 41 | We [explicitly welcome outside contributors](https://github.com/18F/open-source-policy/blob/master/practice.md#accepting-contributions-from-the-public). It’s important to explicitly state how they can help and what they can help with. This part of the website should answer the question: **How can outside contributors become involved?** We include a [CONTRIBUTING.md](https://github.com/18F/open-source-policy/blob/master/CONTRIBUTING.md) file in each repo, which outlines the following: 42 | 43 | * If there are any additional setup steps specific for development. 44 | * Whether there are explicit Instructions for running tests before contributions are accepted. 45 | * If there are any requirements for contribution, if any, e.g. 46 | * A Contributor License Agreement 47 | * CLAHub 48 | * http://oss-watch.ac.uk/resources/cla 49 | * http://contributoragreements.org/ 50 | * If commits should be squashed 51 | * Whether there is a specific coding style to adhere to. (Generally contributors will match what they see within a project.) 52 | * Whether potential contributors should ask before they make significant changes. 53 | * Whether work-in-progress pull requests are ok. 54 | * What 18F's [Code of Conduct](https://github.com/18F/code-of-conduct) states 55 | 56 | **Example:** The README for Midas contains a section called “[How you can help.](https://github.com/18f/midas#how-you-can-help)” What we really like about this section is that it doesn’t assume helpers are developers and lists ways for lots of different people to contribute. (Our [guide to welcoming non-coders to hackathons](https://18f.gsa.gov/2015/04/03/how-to-welcome-new-coders-to-a-civic-hackathon/) also contains many suggestions for ways to involve people with different skillsets.) 57 | 58 | We also recommend reading Midas’ [Contributor’s Guide](https://github.com/18F/midas/blob/dev/CONTRIBUTING.md), which orients new dev contributors and tells them the best ways to communicate with Midas’ dev team. 59 | 60 | ## List the licensing information for your project. 61 | 62 | This part of the repo should answer the question: **What is the license for this project?** All 18F projects are developed in the international public domain whenever possible and contain a [LICENSE.md](https://github.com/18F/open-source-policy/blob/master/LICENSE.md) document, as well as a paragraph at the end of each README which contains information about the public domain. We post this information [in the README](https://github.com/18F/18f.gsa.gov#public-domain), so that users know the code can be adapted and reused, and so they can easily see this information instead of going to a second site. 63 | 64 | ### Include credit and licenses for embedded resources 65 | 66 | If your project includes code or other resources (such as icons, fonts, or photos) from outside sources, your project's license description (in the README, LICENSE, and CONTRIBUTING files) should credit the authors of that work and include their license information. 67 | 68 | It's polite to give full credit when reusing work, even if not legally required by the work's license, and this helps users who want to find the original source and use it. 69 | 70 | We also have a legal responsibility to respect the licenses of work we use. When adapting or embedding outside work, check its license for instructions for complying with that license. 71 | 72 | For example, see ["Licenses and attribution" in the U.S. Web Design Standards README](https://github.com/18F/web-design-standards#licenses-and-attribution). It starts with "A few parts of this project are not in the public domain", to prevent accidentally implying that all the project's files are in the public domain. It lists exceptions in this format: "The file *filename* is from *project name*, by *name of author* [or copyright *name of author*], under *name of license*." Then it has a section titled "The rest of this project is in the public domain", with the typical license information we put in READMEs. The project's [CONTRIBUTING file](https://github.com/18F/web-design-standards/blob/18f-pages-staging/CONTRIBUTING.md) includes the same sections. The [LICENSE file](https://github.com/18F/web-design-standards/blob/18f-pages-staging/LICENSE.md) has the same sections again, plus the full license text for some embedded works and our standard LICENSE information. 73 | 74 | ## List the contact information for your team as well as where to ask questions. 75 | 76 | This part of the repo should make it easy for users to get in touch with the team developing the project. This is also where you should list any listservs, chat programs, or social media groups that have been created to keep contributors informed. 77 | 78 | Any other information that you’d like to share with users can go in the Wiki section of your repository. 79 | --------------------------------------------------------------------------------