2018 content update #36

lauraGgit · 2018-07-19T17:49:29Z

A lot of content changes based off of our growing understanding of this space:

add section about HCD
update tone
reformat FAQ to learn more per GDS suggestions: https://gds.blog.gov.uk/2013/07/25/faqs-why-we-dont-have-them/

Also close: #34.

mheadd

This is great! Just a couple of nitpicky questions.

mheadd · 2018-07-19T18:17:03Z

_strategies/prototyping.md


-Unlike other kinds of prototypes, acquisition prototypes are not typically used as a way to obtain user feedback, but rather to understand the mechanics behind a hypothetical user's experience. It should approximate a user’s experience to help identify risk, and to help validate technical decisions.
+The government should leverage prototypes to garner obtain user feedback, validate technical decisions, and better understand the organizational barriers to deploying software in modern ways.


Does garner or obtain make the most sense here?

ah, yes, will update.

mheadd · 2018-07-19T18:18:38Z

_strategies/prototyping.md


 ### Help the buyer develop prototyping capacity

-Be sure to assess the capability of the client to continue prototype work after the engagement is over. If you’re not helping the buyer develop their own capacity for using prototypes, you’re probably doing it wrong.


This was one of our findings from the AK Medicaid project. Just curious why you eliminated it.

"You're probably doing it wrong" is not a particularly constructive way to frame this finding. I think we could keep it in if we discuss how that can introduce more risk into the project going forward.

I massaged the language a bit and added to the preceding paragraph.

The only thing is this is the only page that kind of talks about the "client" as another entity, rather than a lot of the other pages that speak to "you" or at least the state/government- wonder if we want to reframe in what you added?

Yeah, good point. This was adapted from another source and it still shows that framing.

lauraGgit · 2018-07-19T18:22:32Z

@hannahkane @mheadd @rrefoy @allalala here's the draft build of this version of the site: https://federalist-proxy.app.cloud.gov/preview/18f/modular-contracting-and-agile-development/2018-revamp/

mheadd · 2018-07-19T18:25:08Z

Thanks for the PR @lauraGgit!

Added additional sentence about building internal capacity for doing prototypes.

allalala · 2018-07-19T18:39:14Z

typo at the bottom of the page. Should read As part of the GSA’s TTS

lauraGgit · 2018-07-19T18:43:58Z

@allalala just to clarify which page?

Change framing in "develop prototyping capacity" section.

hannahkane

hope this isn't too annoying. a few typos, but mostly these are style suggestions and can be disregarded if you don't like them

hannahkane · 2018-07-20T00:06:12Z

_data/navbar.yml

@@ -33,7 +38,7 @@ assigned:
              show_in_menu: true
              show_in_footer: false
          -
-              text: Building Prorotypes
+              text: Building prorotypes


typo: prototypes

hannahkane · 2018-07-20T00:08:36Z

_strategies/agile-development.md

@@ -10,36 +10,36 @@ image-credit: https://www.flickr.com/photos/hernanpc/

 ## What is Agile Development?

-Agile development describes a set of principles for building software that allow collaborative, cross-functional teams to accommodate changing user needs and requirements.
+Agile development describes a set of principles for building software that allow collaborative, cross-functional teams to accommodate changing user needs and requirements. Agile development alone will not help you build a good product. In fact, many agile projects fail unless they work to intergrate human-centered desgin.


typo in last word: design

hannahkane · 2018-07-20T00:10:15Z

_strategies/agile-development.md


-To help this process, we pair identifying requirements at a higher level (an “epic” in agile terminology) with an ongoing user research process. These epics describe the user need, not the solution. Through the user research process, these epics are turned into a set of increasingly-specific user stories. This is done continuously, so that user stories are ready for the development team no more than a month ahead of when the development team implements them. (For example, a user story might be: “As a caseworker, I want to see all my current cases and next steps so I know what I need to do next, and when I need to do it.” We wouldn't write: “The system shall display the next step next to each case in a grid on the main screen.”)
+To help this process, we pair identifying goals at a higher level (an “epic” in agile terminology) with an ongoing user research process. These epics describe the user need, not the solution.  For example, a user story might be: “As a caseworker, I want to see all my current cases and next steps so I know what I need to do next, and when I need to do it.” We wouldn't write: “The system shall display the next step next to each case in a grid on the main screen.” Through the user research and usability testing throughout the life of the product development, these epics are turned into a set of increasingly-specific user stories. Each story should be designed, researched, developed and tested within a single sprint. We validate each implemented story with usability testing with real end users, and use the feedback from that work to generate addtional backlog user stories.



typo in last sentence: additional

hannahkane · 2018-07-20T00:11:04Z

_strategies/agile-development.md


-There are three leading causes why IT projects fail: a lack of reliable input from users, incomplete requirements and specifications, and changes in the requirements and specifications. The Standish Group, an IT research firm, publishes an annual report on IT projects, in which they point out that these causes of failure are about the impossibility of “knowing” requirements up front.
+ We prioritize user stories continuously and do not focus on what is in the development backlog beyond what can be done in a month in the future.


suggested rewrite: "...beyond what can be done within the next month."

hannahkane · 2018-07-20T00:13:18Z

_strategies/agile-development.md


-The traditional “waterfall” method of software development assumes that software can be built once for a large, one-time investment. In practice, this is untrue, because requirements can rarely be fully known and change constantly. Users' needs tend to arise through research and testing, and development teams must discover appropriate solutions by building iteratively and interacting with users regularly.
+The traditional “waterfall” method of software development assumes that software can be built once for a large, one-time investment. In practice, this is untrue, because requirements can rarely be fully known and change constantly. The product team's understanding of users' needs arise through research and testing which deepens but shortens your teams forecasting of costs..



Suggest replacing "constantly" with "regularly," "often," or "frequently." Extra period at end of last sentence.

I don't really understand what "deepens but shortens your teams forecasting of costs" means.

hannahkane · 2018-07-20T00:35:04Z

_strategies/prototyping.md


-If the logic behind modular procurement is to break down large projects into smaller chunks to reduce risk, employ this same approach when prototyping. Instead of thinking of a prototype as an immutable whole, consider how it can be broken into pieces to address different questions or technical risks.
+If the logic behind modular procurement is to break down large projects into smaller chunks to reduce risk, employ this same approach when prototyping. Instead of thinking of a prototype as an immutable whole, consider how it can be broken into pieces to address assumptions about customer value and technical risks. Don't obsess about documentation, but highlight to the  what assumption this prototype was meant to assess, and how this tool measured up against those hypothesis.


last sentence has some extra words I think. "...highlight which assumption this prototype was meant to assess"

also last word should be "hypotheses"

hannahkane · 2018-07-20T00:36:23Z

_strategies/prototyping.md


-For example, consider using a boilerplate app (or simple demo app) to support development of a Git merging / branching strategy for a project, or to build out a [DevOps pipeline](/devops), particularly for clients that do not have a well-developed DevOps culture.
+For example, consider using a boilerplate app (or simple demo app) to support development or to build out a minimal [DevOps pipeline](/devops), can help you see where the bottlenecks to agile development will likely occur before a vendor is brought on.


Suggest: "For example, consider using a boilerplate app (or simple demo app) to support development, or building out a minimal DevOps pipeline to help identify bottlenecks in your process before a vendor is brought on."

hannahkane · 2018-07-20T00:37:28Z

_strategies/prototyping.md

 One of the goals of Acq engagements (and [18F engagements in general](https://partnership-playbook.18f.gov/7-transfer-projects-back/)) is to impart strategies and techniques to our clients that will allow them to practice modular procurement on their own going forward, and on other projects. We should intentionally include client staff in prototype work so they have an ownership stake in the process and familiarity with how to use prototyping to support future procurements.

 ### Understand security requirements

 It’s important to understand security requirements in the client environment that can impact prototyping work.

-Does the client have the policy and technical infrastructure in place to support prototyping? Is a full System Security Plan required to build a prototype that isn’t intended to be deployed to a production environment or require ongoing O&M?
+Does you have the policy and technical infrastructure in place to support prototyping? Is a full System Security Plan required to build a prototype that isn’t intended to be deployed to a production environment or require ongoing O&M?


hannahkane · 2018-07-20T00:37:46Z

_strategies/prototyping.md


-Does the client have the technical infrastructure in place to support prototyping? Is test data available for use in building a prototype? Is there an environment where test apps or prototypes can be efficiently deployed?
+Does you have the technical infrastructure in place to support prototyping? Is test data available for use in building a prototype? Is there an environment where test apps or prototypes can be efficiently deployed?


hannahkane · 2018-07-20T00:38:26Z

_strategies/using-cots.md

@@ -12,7 +12,7 @@ image-credit: https://www.flickr.com/photos/butterflysha/

 In some cases, if there is a COTS system that will fit your requirements, then there may be an opportunity for cost savings.

-#### Fully assess whether commercial off-the-shelf (COTS) solutions fit your projects' needs.
+### Fully assess whether commercial off-the-shelf (COTS) solutions fit your projects' needs.


project's (we're assuming a single project elsewhere)

@mheadd

…ing-And-Agile-Development into 2018-revamp Include @mheadd edits

Laura Gerhardt added 10 commits July 18, 2018 15:29

oss changes

0d5735b

oss and prototyping

7eb39de

modular procurement revise part 1

1604abc

backward compatiblity x2

fb89c6d

convert faq part 1

fdf6660

convert faq part II

213c879

incorporate more hcd language in agile page

94a1527

md headings

2908357

add hcd

4ae4a7c

update nav

9e4c5a9

lauraGgit requested review from hannahkane, rrefoy, allalala and mheadd July 19, 2018 17:49

Laura Gerhardt added 2 commits July 19, 2018 14:17

cots part i and spell check

d93aa06

cots part II

f2b945f

lauraGgit changed the title ~~WIP: 2018 revamp~~ 2018 content update Jul 19, 2018

mheadd reviewed Jul 19, 2018

View reviewed changes

Laura Gerhardt and others added 2 commits July 19, 2018 14:26

prototype content tweaks

eb394b7

Update prototyping.md

2073cd7

Added additional sentence about building internal capacity for doing prototypes.

Update prototyping.md

251c64a

Change framing in "develop prototyping capacity" section.

lauraGgit requested a review from jposi July 19, 2018 18:53

hannahkane reviewed Jul 20, 2018

View reviewed changes

Laura Gerhardt added 3 commits July 20, 2018 09:39

fixing grammar, wording

1ec090a

Merge branch '2018-revamp' of https://github.com/18F/Modular-Contract…

3afe26a

…ing-And-Agile-Development into 2018-revamp Include @mheadd edits

fix homepage typo

0413302

jposi merged commit 7e64683 into master Jul 20, 2018

2018 content update #36

2018 content update #36

lauraGgit commented Jul 19, 2018 •

edited

mheadd left a comment

mheadd Jul 19, 2018

lauraGgit Jul 19, 2018

mheadd Jul 19, 2018

lauraGgit Jul 19, 2018

mheadd Jul 19, 2018

lauraGgit Jul 19, 2018

mheadd Jul 19, 2018

lauraGgit commented Jul 19, 2018

mheadd commented Jul 19, 2018

allalala commented Jul 19, 2018

lauraGgit commented Jul 19, 2018

hannahkane left a comment

hannahkane Jul 20, 2018

hannahkane Jul 20, 2018

hannahkane Jul 20, 2018

hannahkane Jul 20, 2018

hannahkane Jul 20, 2018

hannahkane Jul 20, 2018

hannahkane Jul 20, 2018

hannahkane Jul 20, 2018

hannahkane Jul 20, 2018

hannahkane Jul 20, 2018


		Unlike other kinds of prototypes, acquisition prototypes are not typically used as a way to obtain user feedback, but rather to understand the mechanics behind a hypothetical user's experience. It should approximate a user’s experience to help identify risk, and to help validate technical decisions.
		The government should leverage prototypes to garner obtain user feedback, validate technical decisions, and better understand the organizational barriers to deploying software in modern ways.


		### Help the buyer develop prototyping capacity

		Be sure to assess the capability of the client to continue prototype work after the engagement is over. If you’re not helping the buyer develop their own capacity for using prototypes, you’re probably doing it wrong.


		To help this process, we pair identifying requirements at a higher level (an “epic” in agile terminology) with an ongoing user research process. These epics describe the user need, not the solution. Through the user research process, these epics are turned into a set of increasingly-specific user stories. This is done continuously, so that user stories are ready for the development team no more than a month ahead of when the development team implements them. (For example, a user story might be: “As a caseworker, I want to see all my current cases and next steps so I know what I need to do next, and when I need to do it.” We wouldn't write: “The system shall display the next step next to each case in a grid on the main screen.”)
		To help this process, we pair identifying goals at a higher level (an “epic” in agile terminology) with an ongoing user research process. These epics describe the user need, not the solution. For example, a user story might be: “As a caseworker, I want to see all my current cases and next steps so I know what I need to do next, and when I need to do it.” We wouldn't write: “The system shall display the next step next to each case in a grid on the main screen.” Through the user research and usability testing throughout the life of the product development, these epics are turned into a set of increasingly-specific user stories. Each story should be designed, researched, developed and tested within a single sprint. We validate each implemented story with usability testing with real end users, and use the feedback from that work to generate addtional backlog user stories.


		There are three leading causes why IT projects fail: a lack of reliable input from users, incomplete requirements and specifications, and changes in the requirements and specifications. The Standish Group, an IT research firm, publishes an annual report on IT projects, in which they point out that these causes of failure are about the impossibility of “knowing” requirements up front.
		We prioritize user stories continuously and do not focus on what is in the development backlog beyond what can be done in a month in the future.


		The traditional “waterfall” method of software development assumes that software can be built once for a large, one-time investment. In practice, this is untrue, because requirements can rarely be fully known and change constantly. Users' needs tend to arise through research and testing, and development teams must discover appropriate solutions by building iteratively and interacting with users regularly.
		The traditional “waterfall” method of software development assumes that software can be built once for a large, one-time investment. In practice, this is untrue, because requirements can rarely be fully known and change constantly. The product team's understanding of users' needs arise through research and testing which deepens but shortens your teams forecasting of costs..


		If the logic behind modular procurement is to break down large projects into smaller chunks to reduce risk, employ this same approach when prototyping. Instead of thinking of a prototype as an immutable whole, consider how it can be broken into pieces to address different questions or technical risks.
		If the logic behind modular procurement is to break down large projects into smaller chunks to reduce risk, employ this same approach when prototyping. Instead of thinking of a prototype as an immutable whole, consider how it can be broken into pieces to address assumptions about customer value and technical risks. Don't obsess about documentation, but highlight to the what assumption this prototype was meant to assess, and how this tool measured up against those hypothesis.


		For example, consider using a boilerplate app (or simple demo app) to support development of a Git merging / branching strategy for a project, or to build out a [DevOps pipeline](/devops), particularly for clients that do not have a well-developed DevOps culture.
		For example, consider using a boilerplate app (or simple demo app) to support development or to build out a minimal [DevOps pipeline](/devops), can help you see where the bottlenecks to agile development will likely occur before a vendor is brought on.


		Does the client have the technical infrastructure in place to support prototyping? Is test data available for use in building a prototype? Is there an environment where test apps or prototypes can be efficiently deployed?
		Does you have the technical infrastructure in place to support prototyping? Is test data available for use in building a prototype? Is there an environment where test apps or prototypes can be efficiently deployed?

2018 content update #36

2018 content update #36

Conversation

lauraGgit commented Jul 19, 2018 • edited

mheadd left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lauraGgit commented Jul 19, 2018

mheadd commented Jul 19, 2018

allalala commented Jul 19, 2018

lauraGgit commented Jul 19, 2018

hannahkane left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lauraGgit commented Jul 19, 2018 •

edited