{
    "version" : "https://jsonfeed.org/version/1",
    "content" : "news",
    "type" : "single",
    "title" : "18F’s Style Guide for Open Source Project Documentation |Digital.gov",
    "description": "18F’s Style Guide for Open Source Project Documentation",
    "home_page_url" : "/preview/gsa/digitalgov.gov/cm-topics-button-component/","feed_url" : "/preview/gsa/digitalgov.gov/cm-topics-button-component/2015/08/03/18fs-style-guide-for-open-source-project-documentation/index.json","item" : [
    {"title" :"18F’s Style Guide for Open Source Project Documentation","summary" : "We routinely publish our best practices in the 18F Guides, and today we’re happy to launch a new one: the 18F Open Source Style Guide. The Open Source Style Guide is a comprehensive handbook for writing clear, accessible, and user-friendly documentation so that","date" : "2015-08-03T10:00:04-04:00","date_modified" : "2024-04-02T09:45:13-04:00","authors" : {"melody-kramer" : "Melody Kramer"},"topics" : {
        
            "communication" : "Communication",
            "open-source" : "Open Source",
            "software-engineering" : "Software Engineering"
            },"branch" : "cm-topics-button-component",
      "filename" :"2015-08-03-18fs-style-guide-for-open-source-project-documentation.md",
      
      "filepath" :"news/2015/08/2015-08-03-18fs-style-guide-for-open-source-project-documentation.md",
      "filepathURL" :"https://github.com/GSA/digitalgov.gov/blob/cm-topics-button-component/content/news/2015/08/2015-08-03-18fs-style-guide-for-open-source-project-documentation.md",
      "editpathURL" :"https://github.com/GSA/digitalgov.gov/edit/cm-topics-button-component/content/news/2015/08/2015-08-03-18fs-style-guide-for-open-source-project-documentation.md","slug" : "18fs-style-guide-for-open-source-project-documentation","url" : "/preview/gsa/digitalgov.gov/cm-topics-button-component/2015/08/03/18fs-style-guide-for-open-source-project-documentation/","content" :"\u003cp\u003eWe routinely publish our best practices in the \u003ca href=\"https://pages.18f.gov/guides/\"\u003e18F Guides\u003c/a\u003e, and today we’re happy to launch a new one: the \u003ca href=\"https://pages.18f.gov/open-source-guide/\"\u003e18F Open Source Style Guide\u003c/a\u003e.\u003c/p\u003e\n\u003cdiv class=\"image\"\u003e\n  \u003cimg\n    src=\"https://s3.amazonaws.com/digitalgov/_legacy-img/2015/07/600-x-322-screenshot-of-18F-open-source-style-guide.jpg\"\n    alt=\"Screenshot of 18 F\u0026#39;s Open Source Style Guide\"/\u003e\u003c/div\u003e\n\n\n\u003cp\u003eThe Open Source Style Guide is a comprehensive handbook for writing clear, accessible, and user-friendly documentation so that your open source code repositories are accessible both internally and externally.\u003c/p\u003e\n\u003cp\u003eIt’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.\u003c/p\u003e\n\u003cp\u003eIt’s also really important if we want to make outside contributors feel welcome or have outside organizations fork and use our code. (\u003ca href=\"https://github.com/18F/open-source-policy/blob/master/policy.md\"\u003eAnd we do!\u003c/a\u003e) Explaining what a project is, why it’s important, and how people can help ensures that people can fork and adapt our projects.\u003c/p\u003e\n\u003cp\u003eThis 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, \u003ca href=\"https://github.com/18F/open-source-guide/issues/new\"\u003eplease let us know\u003c/a\u003e.)\u003c/p\u003e\n\u003cp\u003eWe’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.\u003c/p\u003e\n\u003ch2 id=\"how-to-use-this-guide\"\u003eHow to use this guide\u003c/h2\u003e\n\u003cp\u003eWe 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. 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.\u003c/p\u003e\n\u003ch2 id=\"the-guide-is-a-living-thing\"\u003eThe guide is a living thing\u003c/h2\u003e\n\u003cp\u003eMost 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.\u003c/p\u003e\n\u003ch2 id=\"now-taking-suggestions\"\u003eNow taking suggestions\u003c/h2\u003e\n\u003cp\u003eIf you’ve got thoughts on how we might improve the guide, please \u003ca href=\"https://github.com/18F/open-source-guide\"\u003esend them our way\u003c/a\u003e—we’d love to hear from you!\u003c/p\u003e\n\u003cp\u003e\u003cem\u003eThis post was originally published on the \u003ca href=\"https://18f.gsa.gov/blog/\"\u003e18F blog\u003c/a\u003e by Melody Kramer, an 18F team member.\u003c/em\u003e\u003c/p\u003e\n"}
  ]
}