usds / playbook Goto Github PK

Is there a downloadable or printable version (other than html) of the playbook? It would be useful if there was one.

Where should playbook readers who want to learn more about any given play turn to look for further information, examples, or advice?

I'm not actually sure how the federated analytics include works, but it looks like you might have the wrong agency and sub-agency:

<script id="_fed_an_js_tag" type="text/javascript" 
  src="/assets/js/federated-analytics.all.min.js?agency=GSA&sub-agency=OGP">
</script>

Reference: https://github.com/WhiteHouse/playbook/blob/gh-pages/index.html#L81

I am an engineer, not a marketer, and like others, I get infuriated by marketing types getting in the way of good technical product, but I have learned the value of branding in establishing ideas and products. This effort will have to penetrate the diverse and labyrinthine cultures of the government, and building good messaging and branding will help.

To build momentum for a cultural shift to embrace the principles in the playbook, you need to develop a connected iconography to represent the Digital Services group, the playbook, the techFAR, and related materials as they are produced. The process of developing iconography can itself be opened up with a public call to artists and a comment process on leading contenders for icons, symbols, and publication templates. One of my earliest lessons in designing software was that visual design counts for a lot.

A slogan could also be useful, though another hackneyed attempt at an inspirational phrase to drive the workforce could backfire.

You also need to publish printable posters and flyers for people to post. People need to be able to "fly the flag," and show that they are on board, and also have an easy way to communicate these ideas to others in their organizations. Initial offerings could be simple pdfs of the list of plays in the playbook in letter-size, tabloid-size, and a size suitable for a large-format printer. The larger format might be able to fit the checklists in. If this effort is to turn into a cultural movement in government, people have to be able to identify themselves as part of the culture.

The introduction to the Playbook could include reference to the TechFAR. At the moment, a search for "TechFAR" gets no results on the Playbook, despite the TechFAR being part of the Playbook.

For Play 6, the product owner (PO) from the government should have deep expertise in the business domain where the software is being built to operate. Often the government places administrative staff in such positions. To describe the PO absent significant business expertise does not allow the PO to effectively guide the development team, rapidly answer questions during sprints, be respected in the field by other business personnel as well as interact effectively with other domain experts when crafting features and capabilities, as well assessing their effectiveness in business use.

Suggesting a 0 play in the nav (or something) to jump the user to the play index more easily.

Currently, if the user is reading one of the plays and wants to get back to the index they have to click the title and scroll down or click 1 and scroll up.

It appears to be a DNS issue. We will update this issue with more information when available.

The three policy oriented items that are critical to government facing applications includes Security, Privacy, and Accessibility (Section 508 compliance, specifically). That needs to be added as it is a critical gap missing from this playbook.

It should not be assumed. Yes, it is part of standards. Yes, it is part of acquisition and selection. And yes, it is often a failure when people "choose commercial technologies" as they have not been addressing the mandate as the government has been required to do, and have not been holisticly impacted by ADA lawsuits for failiing to support the needs of people with disabilities, or the adaptation and modification of content by end users such as those using assistive techologies

I’m not sure where this topic plugs into the playbook.

Lots of agencies produce KML/KMZ files. It is extremely easy to display such files with the Google map API. As a result, independent online map developers can help bring visibility to data in these types of files.

However, in order to make KML/KMZ files that are widely usable, the staff producing these files need to be educated on two points.

First, big files should be broken into several smaller files.

The Google map API limits KML files to 10MB and KMZ files to 3MB.
https://developers.google.com/kml/documentation/mapsSupport

If data exceeds these limits, then it is easy to make a small KML file that uses several NetworkLink tags to display all the data on one map. Each NetworkLink points to a KML or KMZ file that fits within Google’s specs.

I do not know if the OSM or ESRI’s API have their own size constraints on KML or KMZ files. If they do, then of course the most restrictive size limits should be used.

Second, in my experience most software that generates KML/KMZ files creates a jungle of junk tags. All too often the KML parser used by the Google map API refuses to render these files at all. By “junk tags” I mean ones that might mean something to Google Earth and 3D viewing. However, I expect in the vast majority of cases the agency that is producing the KML/KMZ file does not care one whit about 3D and simply wants to get their data in front of as many eyeballs as possible. The way to achieve that goal is to use KML/KMZ generating software that only (1) produces 2D tags that (2) are understood by the three most popular map APIs (Google, OSM, ESRI). It is possible that such a tool would have to be written.

Joseph Elfelt

It's currently filled with spam.

I'd like to propose that you wrap each of the headings in an anchor:

<a href=#play1>
  <h1>Play 1 Title</h1>
</a>

This would allow one to click on the title of the heading and get a URL like http://playbook.cio.gov/#play1. If you want to share a particular section of the playbook with someone, having the section's id in the URL is helpful.

See the Bower documentation for an example of this functionality.

Playbook #6. Cannot assume someone who is "the leader" has the authority to act - classic government mistake is to put someone in charge with no real power over people involved. Needs to be 3 parts. "Assign one leader, ensure they have authority to get the job done, and hold that person accountable."

The U.S. Digital Service, and its Playbook and Handbook, should advise conformance with, and themselves conform to, ISO 8601, the international standard for unambiguous datestamps, and the US versions thereof, ANSI INCITS 30-1997 (R2008) and NIST FIPS PUB 4-2.

I just downloaded "TechFAR Handbook 8 7 14.pdf".

At minimum, that should change to one of these:

• "TechFAR Handbook 2014-08-07.pdf" (if as of August 7)
• "TechFAR Handbook 2014-07-08.pdf" (if as of July 8).

Please see:

• XKCD on the subject
• DBpedia page
• Wikipedia article
• ISO 8601 info page
• ordering ISO 8601:2004
• ordering ANSI INCITS 30-1997 (R2008): Representation of Calendar Date and Ordinal Date for Information Interchange
• NIST FIPS PUB 4-2, Representation of Calendar Date for Information Interchange (1998-11-15) (withdrawn in United States 2008-09-02)

" Even though Agile software development is a new practice to the Government, it dates back to the 1970s ..."

Actually in Government related projects, dates back to the 1950's with NASA and IBM Federal Systems Division.

Reference:
"Iterative and Incremental Development: A Brief History", Larman and Basili
Note 1950's activities presented on the first page.
http://www.craiglarman.com/wiki/downloads/misc/history-of-iterative-larman-and-basili-ieee-computer.pdf

Great site, first of all.

The only issue I have is that the numbered play links give no indication of what the play's title/content is. This makes it hard to semantically navigate the massive amount of content. At present, the link's title attribute shows on hover, however these simply say something like "View Play 2", and only appear after hovering for nearly 1 sec (in Chrome at least).

My suggestion would be to create an immediate hover effect that displays the actual title of the chapter (you could use something akin to Bootstrap's Tooltips).

Something like:

"Question: FAR 42.302 lists the contract administration functions [...snip...] When performing contract administration, agencies have noted challenges in committing staff to support Agile software development. Is Agile software development feasible given agencies’ limited resources? "

It should be noted that Agile development is based on producing release candidate quality software on an iteration basis. It is far easier to assess the health of contract performance by observing and measuring actual results (working software, as assessed by the customer) that the greater work necessary to observe interim artifacts (project plan milestones, task progress, et cetera) with methodologies that perform infrequent software delivery. This should be covered more clearly in the text section, "The emphasis on working software over documentation [...snip...]"

Second, more linear software development methods tend to have significant contract administration activity toward beginning and end of contract, and especially at end when contract performance issues become evident as software goes to integration and deployment. Agile smooths out contract administration as a more constant, lower effort of on-going activity.

Replace sprint by iteration in all uses except when using Scrum example.
Change 1-4 weeks to 1-8 weeks for iteration cycles globally
page 4 footnote 8 - the small team size is for the core team. There may be a large support team of people that are used occasionally or for support requirements. Also, the product owner is not the leader. Several Agile approaches do not have a leader but are self organizing. There will be a sponsor but that is not the same as a leader.
page 13 The product owner uses the demonstration as the primary method to determine if the software is responsive aided by the acceptance criteria for each user story or other requirement format.
page 28 change user cases to user stories (or use cases)
page 29 footnote 27 ...velocity typically stabilizes in a small range...
page 34 The project manager is not sometimes called the product owner. These are two separate roles. The product owner is a functional role not a project management role. Sometimes one person fills both roles.

Alternatively call this new play “Develop, maintain and use metadata”.

OK, I’ll ’fess up. I have a database background so naturally this is the first thing I saw when I reviewed the work done to date. This is such an important concept that it deserves its own play. And even though private enterprise got religion over data dictionaries many years ago it would be a mistake to assume that all federal agencies have also seen the light.

The three most important elements of a data dictionary are:

1. Adoption of a naming convention for data elements
2. A few sentences describing the information captured by each data element
3. Enforcement by senior management

How can systems be built at all, never mind quickly and efficiently, if people are calling the same piece of data by different names?

How can the public readily understand the information conveyed by a downloaded spreadsheet if there is not a short narrative description of the data shown in each column?

Joseph Elfelt

Not sure if this is wrongheaded, but it may be a good idea to change the css file to be permanent instead of a relative url so that http://whitehouse.github.io/playbook will look like http://playbook.cio.gov/. A small thing but maybe worth doing.

Despite the best efforts of thousands of people, all sorts of things go wrong with the design and delivery of large-scale digital services. Therefore, what advice should we give to playbook readers about how to prepare, respond, & learn from things going wrong with their digital services?

I like the Playbook http://playbook.cio.gov/
Once suggestion is to change the alt-text so when I hover-over the Play numbers in the top right it shows me the title of the Play instead of "View Play 8"

Where the content in the TechFAR provides guidance on executing a play, the playbook should link directly to a particular section. Likewise, the TechFAR should reference plays. The documents should work together.

In the executive summary of the TechFAR document, paragraph 4 begins:

In every agency, there are multiple stakeholders who share in the responsibility for achieving successful results from their IT investments and who form the acquisition team, including program officials, IT officials, acquisition officials, and agency legal counsel.

Shouldn't end users (either within or without the acquiring agency, as appropriate) be included here somewhere?

Consider something similar to Amazon's play: "All teams will henceforth expose their data and functionality through service interfaces"

More reading here:

http://apievangelist.com/2012/01/12/the-secret-to-amazons-success-internal-apis/

Minimal Viable Product should be introduced earlier in the agile description section (rather than first showing up in the Q&A). The notion of building MVP key capability (over nice to have features) through a prioritized product backlog is an exceptionally important concept - knowing the right and necessary software is built as soon as possible, reducing risk, staying focused on what matters most, et cetera.

A bit nitpicky, but true all the same. Although it is an acronym, only the first character of Sass should be capitalized. The docs only refer to it as Sass, never SASS.

In my experience, part of the reason that everyday Americans don't trust government is that they simply don't see its presence, authority, or resources in their everyday lives. There are lots of reasons for this, but sometimes, it is because government is actually working well, doing what it needs to do.

As part of the USDS Playbook, I would recommend adding a play: "When it works, make it known."

Just as a truly digital government should seek to understand what people need, it should also inform people when it has built a quality service in the manner that suits their needs. We citizens could serve to be reminded of the value that government offers to our lives when it works well, so that we can rebuild faith in public institutions.

[I got on Github for the first time so that I could make this comment. Apologies if I put it in the wrong place - and thanks for incorporating its intent into your process.]

"Project Manager: Government manager of the Agile process. Also sometimes called Product Owner."

It would be wise to break out these two definitions. The roles are suitably different (and important). One can certainly note, in the case of smaller efforts, the role could be performed by one person.

To not have a Product Owner identified as a key government person is a significant impediment! Amongst other things, the Product Owner can not be administrative - it most have business expertise. They should, for example, be able to answer 80% of all questions asked by the development team within a few hours (either by knowing the answer or who to ask). Especially as the government looks to do Agile, it must understand this role within its organization and how it is key to successful solution delivery to the business.

The first checkbox in Play 1 is "Early in the project, spend time with current and prospective users of the service". However, there's not any guidance on how to find and initiate communication with prospective users.

I think it would be helpful to have some content on how to publicize a project so that potential users and contributors can find out about it in the first place. For example, is there set of common locations to make sure you post the project? Websites? Forums? Mailing lists?

"Page down" on a PC goes "too far" since it doesn't know about the fixed navigation header. Fix this with a media query so when header appears there is some extra margin or padding on the content area.

When I first saw the playbook when it was announced, it was obvious that it came out of the White House, but that's because I read the blog post.

Today, when I went to it, it dawned on me that someone coming into it blindly may now know this is an official government work. It struck me that there was no context. Perhaps a logo in the header/footer or referential USDGS text would help.

Related discussion: https://twitter.com/mollieruskin/status/519583622706130944

Any new federal website should be using HTTPS by default. In 2014, there just isn't a good reason to not do so.

I realize that you are using github pages for playbook.cio.gov, and that github pages does not let you use a custom domain name with HTTPS (see https://konklone.com/post/github-pages-now-supports-https-so-use-it for more info). Until github fixes this, the right solution is for you to host your website elsewhere. Perhaps you could use Amazon Cloudfront+S3, which supports HTTPS for free, and allows custom domains.

HTTPS by default is the right thing to do, and you should be setting a good example for other agencies. Plus, it will help your Google pagerank (see: http://googleonlinesecurity.blogspot.com/2014/08/https-as-ranking-signal_6.html)

I want to collaborate on a multi-platform public information tool for before, during and after crises that makes info from Federal, State and local Emergency Management and Public Health agencies more understandable and actionable.

"1. Change #plays_index background color to #a7d2e3 and all text color (including links) to #cccccc
2. Change #navigation_bar ol background color to #a7d2e3 and all text color to #cccccc
3. Change #plays h4 and #plays ol list-style-icon to have a color of #32436e. This will require changing the svg image (sorry Mollie).

Love,
18F"

On my Macbook Pro's retina display, the USDS logo is a touch blurry:

I'm not totally sure what the best practices are in providing 2x images for retina display, or letting the browser size it or whatever, but wanted to at least flag it.

I appreciate the current design. I think there are two ways it can be improved:

1. Create a more impactful summary that really captures the core principles. Sort of an exec summary meets the Agile Manifesto.
2. Create drill downs where additional supporting content can be added. For example I created an illustrated educational video on how Healthcare.gov could have been done using Agile. https://www.youtube.com/watch?v=vvfI9XsBuXo I think this definitely supports the Playbook's goals with solid educational content. I don't know where it would link in the current design.
   Thoughts?
   Robin Dymond
   www.innovel.net

Structure the playbook so that agencies can contribute content in the margins, provide examples of how they have executed plays, etc. This could help increase the likelihood of adoption inside agencies.

Agencies should be able to contribute case studies and templates to show how they have addressed each of the checklist items.

Normally the release backlog is prioritized with the most important stories at the top. The sprint backlog is then pulled from the top of the backlog. The diagram gives the impression that the stories at the bottom of the release backlog are composing the sprint backlog. I suggest changing this.

There are two HTML elements in the playbook with an id of "plays":

$('[id="plays"]') //[<a class=​"anchor_offset" id=​"plays">​</a>​, <div id=​"plays" class=​"outer_container">​…​</div>​]

HTML element ids need to be unique.

There's a saying that "writing software is cheap, maintaining it is expensive". When writing digital services, it's tempting to believe that there will come a time when they're "done". In practice, that isn't the case, as these services exist in an ever evolving environment:

• technologies to create, maintain and access digital services change
• user, developer and administrator expectations change
• regulations and other requirements change

Sometimes it's even necessary to swap out the entire technology stack of a digital service, without breaking other applications written to use that service.

Small startups and relatively new companies don't need to worry about these things, as it doesn't make much sense to expend energy on issues that are likely years away from causing problems, when your main concern is whether or not you'll be able to pay the bills next month. Writing "institutional software" that may end up being in service for decades is a different story - it's necessary to recognise up front that the "care and feeding" of these services is something that will require ongoing investment for as long as the service is in operation.

Many of the other plays (especially the use of agile iterative practices and the use of automated testing) are specifically aimed at implementing a sustainable approach, but step one is really to acknowledge the need for long term sustainability in an institutional context.

Somewhere in the process it might be helpful to suggest that agile process workpapers and artifacts should collate into an articulated document as a proxy for work-in-process (and potentially thereafter) documentation...as this is one of the most common problems of “ad hoc” development. It can be accomplished in various ways from a wiki to a conscientious effort to stream the abstraction process using artifacts (potentially in journal form - which may be reviewed or not) depending on the criticality of the mission software. Making knowledge transfer a priority from early planning through execution will assist the process at every level and is unlikely to occur without specification. I could go on but I'm hoping the group gets the point and will help expand on the concept. Specification must begin early and documentation is important for improvement and innovation. I'm simply guessing clients would like to assist innovations/improvements after the project is complete...particularly when released to open source.

We should have a custom print CSS style.

why does playbook bind to a specific ruby version?

https://github.com/WhiteHouse/playbook/blob/gh-pages/.ruby-version

Mangled and used 2.1.2, worked just fine

Consider adding to the open data checklist:

• Release large datasets incrementally
• Do not wait for the data to be ‘perfect’ before releasing it
• Release metadata in addition to data
• Provide public access to GIS servers or explain why not

Here are the reasons for these suggestions.

I am a Google map API developer. One of my projects is Gmap4 which I audaciously describe as an enhanced Google map viewer. One feature of this browser app is the ability to display data that is hosted on GIS servers (MapServer and WMS now, ImageServer real soon now). Last summer I began looking for Forest Service (FS) recreation data that might be useful to show on an online map.

A search led me to the FS GIS server at http://apps.fs.fed.us/arcx/rest/services which included, at that time, lots of trail data including line coordinates. Sweet, thought I. Along the way I traded email with various FS employees and consultants. Then the trail data disappeared from this GIS server. Apparently, until I happened by, FS management was not aware that anyone with a bit of knowledge about the ESRI REST API could access this trail data. The excuse I was given is that the trail data is draft and has not yet been designated “authoritative” by FS management.

However, before this trail data was removed from public access, I downloaded KMZ files with the trail data for all the national forests in Washington, Oregon and California. (Certainly if I had suspected the FS was going to soon bar the public from seeing this trail data I would have downloaded more of it.)

Yes, the national forest trail data for these three states is incomplete and some of it is wrong. But the FS trail data that exists is a lot more right than wrong at least in the three states where I have seen the data. You can see the data too. I wrote code to cleanup the data and process it into a more useful form. Then I produced one Gmap4 link for each national forest in WA, OR and CA. There is a link to those maps near the top of my ‘Examples’ page: http://www.mappingsupport.com/p/gmap4_examples.html

So even if the FS trail data for other areas is more bad than good, that is not a valid reason for refusing to let the public see the trail data for areas where the data is, in fact, more good than bad. And if the misguided policy is to wait for the trail data to be perfect before letting the public see it then the trail data will never become open since some of it, despite all efforts, will always be wrong.

The playbook talks about delivering software in increments. Great! Let’s deliver data the same way.

Part of my experience with the FS also supports my suggestion that metadata be added to the checklist in order to highlight the importance of metadata to everyone including FS staff, consultants and the public.

After learning that the FS had recreation data stored in several major systems, including on a GIS server, I innocently asked for a copy of the data dictionary for each such system. Since my polite request was ignored, I filed a FOIA in October 2013. At no time did the FS ever claim that these data dictionaries did not exist.

The FS says it has fully complied with my FOIA. On April 29, 2014 I filed a FOIA appeal with the FS Chief’s office since I have not received the data dictionary for the three systems known as INFRA, Portal and GIS. So far the FS has not responded on the merits of my FOIA appeal. Sheesh! It’s not like I’m asking for the combo to the safe at Fort Knox.

Now lets look at public access to GIS servers. Anyone with some coding aptitude and the ability to self-teach can learn how to display MapServer or WMS tiles with their own code. There are various APIs that assist with this task including ones from Google, ESRI and OSM. I can certainly see some agencies wanting to extract GIS data into something like KMZ files and then only letting the public see the KMZ files and barring the public from direct access to the data on the GIS server. This approach creates a variety of problems/questions:

1. Which data is more current? GIS or KMZ?
2. Which data is more complete? GIS or KMZ?
3. Which data has better metadata? GIS or KMZ?

Also compare an app that fills the user’s screen with tiles delivered by the GIS server to an app that fails to render KMZ data at all since (A) the file is too big and/or (B) the file is full of ‘junk’ tags that break whatever is being used to parse the KML. I can report on good authority that both A and B are common.

And then there are agencies that do not provide either GIS access or KMZ files. Here’s an example. In 2013 I traded email with the National Park Service (NPS) GIS staff. Those staffers access a GIS server and produce various online maps. I wanted to produce online maps showing their data with my own software. After I failed to find the address for the NPS GIS server online I asked staff to share that address with me. They refused and said the public is not allowed access to that server and its data. The links I sent them for the President’s executive order on open data and the followup memo from OMB had no effect. In December 2013 I filed a FOIA with the NPS for access to the recreation data on their GIS server. So far the NPS has not even acknowledged receipt of this FOIA let alone responded on the merits.

Finally, just one tiny blatantly self-serving plug. If anyone wants to know more about Gmap4, the best documentation is currently on the beta page:
http://www.mappingsupport.com/p/gmap4_beta.html

Joseph Elfelt

Today, too many of our digital services projects do not work well, are delivered late, or are over budget. To increase the success rate of these projects, the U.S. Government needs a new approach.

The main reason that projects do not work well or do not meet delivery dates or budget expectations is that the goals are simply unrealistic given the actual resources available.

Contract allows the government delivery team the flexibility to adjust feature prioritization as the project evolves.

This is going in the right direction as far as providing some flexibility in project contraints, but only mentions one aspect -- scope -- and to a limited degree. See the "Iron Triangle" or PMBOK Star etc. Working within that structure of constraints and flexibility in all project management areas including resource allocation, scope, schedule, etc. are necessary for success.

These types of issues are directly affected by political situations, and so projects cannot be successful without successfully managing exterior politics that intersect at the project outset and throughout the process in a way that continues to align with the selected project configuration given the constraints.

All sites developed for the government, regardless of department should have a consistent look, feel and functionality. Once a user becomes familiar with the functionality, they will be able to leverage what they have learned when visiting other government sites.

Using ".docx document" link on https://playbook.cio.gov/techfar/:

https://playbook.cio.gov/assets/TechFAR%20Handbook_2014-08-07.docx
WARNING -- Access to this file is blocked by security measures for the following reason:

• File type attempted to download not allowed.
  If you feel you have reached this message in error, you may contact the Service Desk at 5-4357 or the Network Operations Center at 5-7370.
  File name: TechFAR Handbook_2014-08-07.docx

Don't need the document, just passing it along.

What about adding something related to enterprise architecture and governance to help coordinate and amplify the value added?

There still seems to be confusion about what this is and how it should be used. The Definition of Done should not be defined in the PWS. It can not be specified upfront. It will evolve as the team works. It is a checklist of what the team must complete do for every user story in the product backlog. The government (Product Owner) does provide input to it. Generally this involves the PO stating a requirement (e.g. user story must be Section 508 compliant) and the team then adding checklist items to the Definition of Done which are necessary to meet that criteria for every user story. In the retrospectives they may decide that adjustments are necessary to the Definition of Done. Thus, the Definition of Done is the team's to own and define. It can not be stated in the PWS. Perhaps it can be stated in the PWS that a Definition of Done will be required and approved by the government's Product Owner.