| permalink | layout | title |
|---|---|---|
/submit/style-guide/ |
page |
Style Guide |
This guide is intended to help government employees and civic hackers to better tell their story about their awesome open source, open data, and open government efforts. For more background, include project goals and scope, see the project readme.
Note: Do not feel that you need to adhere so strictly to these guidelines as to stifle your own writing, but some baseline level uniformity between stories is desired for the readers' sake.
Government.github.com is a government-centric microsite dedicated to showcasing and amplifying best practices and first-of-their-kind efforts within government around open source, open data, and open government. In addition to a series of short, informal blog posts written by the public via pull request ("stories"), the completely open source microsite will also curate government-specific collaboratively edited documentation such as FAQs, or links to the public-facing GitHub profiles of government agencies.
Stories should be informal and friendly while still remaining fact driven and authoritative. Write like a human writing for an audience of other humans. Avoid jargon and overly-complex or technical language. Write in the third person.
Stories should be brief (roughly 4-5 paragraphs) and should be written similarly to a blog post on a personal blog. Use proper grammar and punctuation. Links are encouraged.
Stories do not have to strictly follow the five-paragraph template, but can use the following as a guide / the ideal in hopes of keeping posts tight:
- What your agency does
- Problem faced
- Traditional approach
- Approach taken
- Outcome / Results (A+ for numbers)
- In a sentence or two, what's your department's mission/role? Introduce yourself to the world.
- What services or "products" is your department typically charged with delivering to customers, both internally and to citizens? How do you normally do it?
- What was the challenge / opportunity you faced?
- How would you have normally approached that challenge? Why didn't you do that?
- What did you do instead? Why was that revolutionary?
- What was the outcome / result? What kind of feed back have you received, both internally and externally?
- Any numbers you can share (cost savings, engagement, etc.?)
- Has your experience changed how your team works on a day-to-day basis or how it approaches new problems?
- Where do you see these efforts in two years? in five?
- Any words of advice / lessons learned you'd pass along to others in a similar place?
- Anything else we should have asked / you'd love the world to know about your efforts?
Headed by the US Chief Information Officer, the Office of Management and Budget's Office of E-Government and Federal Information Technology was tasked by the President's Digital Strategy with drafting a comprehensive open data policy for the federal government. Such a document required collaborating among countless stakeholders, both inside the white house and across various federal agencies. Given the rapid pace of technology the document's drafters feared that the policy could very well be outdated even as early as the day of its release.
Historically, such policy documents would be drafted using traditional desktop-publishing software, shared among stakeholders via e-mail, and ultimately published as a final and static PDF. Given the scale and pace of the undertaking, the Open Data Working Group adopted GitHub as the primary collaboration platform, not just for the policy's accompanying source code, but for the policy itself as well.
The policy was ultimately published on GitHub as a living, collaborative document. Today, any federal employee or member of the public is encouraged to submit proposed improvements to the policy or any of its accompanying material. The document itself is stored as a series of Markdown files within git, the underlying version control system which tracks and makes publicly available, a detailed history of who made what changes to the document, and is published as a free, static webpage using GitHub Pages.
To date, more than 75 discussions and proposed changes have been submitted, from small grammatical errors, to adding additional resources, to a mobile-first redesign of the document. Stakeholders regularly review the feedback received and ultimately accept or reject each proposed change. The document has been updated nearly 100 times since its release (a first for a government policy document), and the community shows no signs of slowing.