18f/open-source-guide

18F’s Style guide for open source project documentation

open-source-guide's Issues

Spelling of FAQ

I make the recommendation to change the spelling of FAQ. Do not use "FAQS", "FAQs", or "faqs". Many styleguide experts argue for the "s". This is a personal preference. Looks cleaner and historically seems to be the original presentation.

repo stands for repository

I'd suggest just using "repository" throughout the document.

Add an example of how to make a pull request

I feel like we should just take the entire CONTRIBUTING.md file from College Scorecard and include it here as a great example of a way to teach newbies about GitHub and welcome contributions. https://github.com/18F/college-choice/blob/dev/CONTRIBUTING.md

h/t to https://twitter.com/vtcraghead/status/643609201126834176

Suggestions for naming?

I was hoping you all might be open to discussing a few slightly more prescriptive guidelines for naming conventions. There are two areas in particular that I think are problematic in our industry with regard to naming, which makes projects especially hard to find (especially if you're looking for docs or support) :

1. Avoid "clever" naming. The world has a lot of projects with puns in the name or other cleverness that makes them rather hard to find. For example, the number of Javascript projects with some coffee-pun in the title is enormous. It'd be useful if developers were encouraged to avoid names that are just jokes and ambiguous. (I'll take postgresql-node-session-connector over Barista any day.)

2. Check to see that the name isn't already used. I've brought this up before but it's also really hard to find projects when they're using a name that's already used by another highly-used project. A quick google search before deciding on a name can save lots of time for your users later.

merge (or link between) related resources

We have some other related resources:

• https://pages.18f.gov/before-you-ship/
• https://pages.18f.gov/open-source-program/pages/maintainer_guidelines/
• https://github.com/18F/open-source-policy/blob/master/practice.md

@melodykramer Did you go through each of these already to consider what content should be where, or is it worth another pass?

Integrate Britta's notes

https://docs.google.com/document/d/1a_APYNHEu74UrNRs98CmkebkEw3mL2HS2MrRDln72Ok/edit

/cc @brittag

Add guidance for all the things our software should ship with

Karl Fogel's "Producing Open Source Software" recommends each open source software package include a:

• README file
• INSTALL file
• LICENSE file
• CHANGES file (CHANGELOG or NEWS)

See: http://producingoss.com/en/producingoss.html#packaging

In the top level of new directory tree, there should be a plain text README file explaining what the software does and what release this is, and giving pointers to other resources, such as the project's web site, other files of interest, etc. Among those other files should be an INSTALL file, sibling to the README file, giving instructions on how to build and install the software for all the operating systems it supports. As mentioned in the section called “How to Apply a License to Your Software” in Chapter 2, Getting Started, there should also be a COPYING or LICENSE file, giving the software's terms of distribution.[64]

There should also be a CHANGES file (sometimes called NEWS), explaining what's new in this release. The CHANGES file accumulates changelists for all releases, in reverse chronological order, so that the list for this release appears at the top of the file.

Govfresh suggestions to make guide more helpful

Additional thoughts that would make the guide more helpful from Govfresh:

• Add a section on collaborators and permissions.
• Encourage including a link for the ‘Website for this repository’ next to the description whenever possible.
• Next to the ‘Edit this page’ link, add a ‘Submit feedback’ link to the issues section for the guide so it’s easier to giv feedback. In general, if you’re going to have either option, it’s best to have both, especially the latter.
• One bug: The images on https://pages.18f.gov/open-source-guide/using-the-wiki aren’t responsive.

give attribution to CFPB for the theme

We've been using DOCter for these types of pages a lot (which is good!). But we don't send any kind of link or attribution back to https://github.com/cfpb/docter. We should.

Two Broken Links on Making ReadME Page

There are two broken links on this page ( https://pages.18f.gov/open-source-guide/making-readmes-readable/ ).

The links are "developing the site" - ( https://github.com/18F/18f.gsa.gov#developing-the-site ) and "deploying the site" - ( https://github.com/18F/18f.gsa.gov#deploying-the-site ).

Not sure why the "18f.gsa.gov" is in the middle of the link and not proper ReadMe.

As a person who is setting up their first open-source repo, I'd like to know if there's any actions I should take to make my repo more friendly for people to submit issues to.

I've read the sections on structuring my own issues and creating README's, but is there anything that I can and should do to help structure how people submit issues before the repo is live?

For issue submitters, I'd like to make that experience a positive and easy one.
For my project team, I'd like to make sure that we receive issues and feedback that we can make actionable.