18f / open-source-guide Goto Github PK
View Code? Open in Web Editor NEW18F’s Style guide for open source project documentation
Home Page: https://open-source-guide.18f.gov/
License: Other
18F’s Style guide for open source project documentation
Home Page: https://open-source-guide.18f.gov/
License: Other
Additional thoughts that would make the guide more helpful from Govfresh:
I'd suggest just using "repository" throughout the document.
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.
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.
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) :
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.)
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.
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.
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
We have some other related resources:
@melodykramer Did you go through each of these already to consider what content should be where, or is it worth another pass?
Karl Fogel's "Producing Open Source Software" recommends each open source software package include a:
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.
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.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.