Knowledge transfer

[HABruce]

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.

[wvchris]

When VISTA is Open, it is Open. When you get the software, you get the software. It is an interpreter and actually runs the source code. This is why we can capture the line of code when there is an error. There is over 1.6 gigabyte of documentation available from the VISTA Documentation Library. This has been extracted and collected so that the documentation can be freely distributed to any who wants it. VISTA is all about technology transfer in this countryand over-seas..

[cew821]

@HABruce Thanks for the comment. I think you are referring mostly to documentation related to how the service is built, for the benefit of knowledge transfer to other team members who will be adding features or doing maintenance on the software in the future. Is this correct?

[ruckc]

My frustration in my arena is that the amount of documentation "required" often never gets read and stifles the speed of development. We've been working to autogenerating documentation through proper commit logs, and auto generated documentation (i.e. javadocs and comparable documentation for web services). It pains me to no end that for a single "commit" to a repository we require 4 word documents currently to go along with it.... that don't get read.

Curtis

On Mon, Aug 25, 2014 at 6:46 PM, HABruce notifications@github.com wrote:

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.

— Reply to this email directly or view it on GitHub https://github.com/WhiteHouse/playbook/issues/59.

[HABruce]

I mentioned this because documentation is a well known weak point of open source software...particularly in an enterprise application because many different users, with a variety of skill levels, interact with the software. What's obvious to developers/coders are often not obvious to users (or subsequent programmers) who must follow and comprehend the logic of the code...subtle, pristine or otherwise. Agile processes (particularly planning sprints and scrums) create perfect auto-generating opportunities as an integral part of the process...cradle to grave. It is up to the commit (submitter) to make her process clear and careful attention must be paid to assure it is organized/categorized/accessible...volume not equal to any of these characteristics. In the enterprise, coding an application is only part of integrating it's usefulness into an organization...which occurs repeatedly over the useful life of the programming. I like the old saying that the best contracts are the ones that never get read...the same is true of documentation...for much the same reasons.

On 9/10/2014 5:40 PM, ruckc wrote:

My frustration in my arena is that the amount of documentation "required" often never gets read and stifles the speed of development. We've been working to autogenerating documentation through proper commit logs, and auto generated documentation (i.e. javadocs and comparable documentation for web services). It pains me to no end that for a single "commit" to a repository we require 4 word documents currently to go along with it.... that don't get read.

Curtis

On Mon, Aug 25, 2014 at 6:46 PM, HABruce notifications@github.com wrote:

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.

— Reply to this email directly or view it on GitHub https://github.com/WhiteHouse/playbook/issues/59.

— Reply to this email directly or view it on GitHub https://github.com/WhiteHouse/playbook/issues/59#issuecomment-55187449.

[HABruce]

Originally yes... However, I suppose I should take the perspective that documentation should be broadly useful...from a cradle to grave perspective (planning to packaging), documentation is important. By definition, all of the process may be of interest in the future. This is a long term commitment to a mission critical application...quite different from a personal desktop application.

On 9/10/2014 5:13 PM, Charles Worthington wrote:

@HABruce https://github.com/HABruce Thanks for the comment. I think you are referring mostly to documentation related to how the service is built, for the benefit of knowledge transfer to other team members who will be adding features or doing maintenance on the software in the future. Is this correct?

— Reply to this email directly or view it on GitHub https://github.com/WhiteHouse/playbook/issues/59#issuecomment-55183869.

[rdymond1]

Documentation needs to have a clear consumer. If we don't have someone complaining that they need to read it, we are creating documents for no one, and that's pure waste.

Software developers generally know better than to rely on documents to describe what the software does. They can run tools to understand the structure and read code to understand what it does. Documentation is not a good way to describe what code does. Acceptance and unit Tests are better. Especially when they are automated.

Documentation needs consumers, and so user manuals, operations manuals, and help docs are useful. So are docs to meet regulatory needs, for example the FDA.

Robin Dymond, CST Managing Partner, Innovel, LLC. www.innovel.net www.scrumtraining.com Americas: (804) 239-4329 twitter: @robindymond Linkedin: http://www.linkedin.com/in/leanagileexecutive

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.

— Reply to this email directly or view it on GitHub https://github.com/WhiteHouse/playbook/issues/59.

[HABruce]

I don't mean to seem argumentative...BUT Waiting for someone to complain and/or refusing to anticipate consumer needs doesn't really answer the learning loop (feedback) requirement for quality improvement. There is no doubt different consumers have different needs but it should be obvious which groups need what level of information...evidence of complaints by consumers is overwhelming...as is the efficacy of requesting documentation after the fact. As projects age (grow larger by accretion), planning constraints and design intent are easily lost on incremental developers who, in turn, contribute to a breakdown (rather than build-up of clarity and continuity (maintainability) of the code base. I could go on but I think you get the idea. I tend to see these government projects as having longer life cycles than personal use applications. For example, a quick survey of FDA documentation requirements should leave you with a clear understanding that process documentation is a fundamental requirement...much of it difficult (expensive) to produce after the fact. I happen to believe it's easier/smarter to get it as close to right as possible the first time...particularly if you accept the "good enough" premise upon which many (likely most) incremental, open source/agile projects depend. Just my opinion...you be the judge.

On 9/10/2014 9:06 PM, Robin Dymond wrote:

Documentation needs to have a clear consumer. If we don't have someone complaining that they need to read it, we are creating documents for no one, and that's pure waste.

Software developers generally know better than to rely on documents to describe what the software does. They can run tools to understand the structure and read code to understand what it does. Documentation is not a good way to describe what code does. Acceptance and unit Tests are better. Especially when they are automated.

Documentation needs consumers, and so user manuals, operations manuals, and help docs are useful. So are docs to meet regulatory needs, for example the FDA.

Robin Dymond, CST Managing Partner, Innovel, LLC. www.innovel.net www.scrumtraining.com Americas: (804) 239-4329 twitter: @robindymond Linkedin: http://www.linkedin.com/in/leanagileexecutive

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.

— Reply to this email directly or view it on GitHub https://github.com/WhiteHouse/playbook/issues/59.

— Reply to this email directly or view it on GitHub https://github.com/WhiteHouse/playbook/issues/59#issuecomment-55206473.

[rdymond1]

Fortunately I don't have to rely on opinion for this issue.

Client #1 uses Scrum for creating software to operate Pacemakers. They have significant FDA document requirements, and automated testing to prove every change is defect free. They have been using Scrum since 2008. Their is no more mission critical an application then running a pacemaker.

Client #2 uses Scrum with a product development division of over 400 people. Their product is a complete solution to operate a hospital. Over 1600 hospitals across Europe use their solution to do everything from schedule hospital beds to manage the Emergency room. The solution has been actively developed for 15 years. Their competitors in the USA, McKesson and General Electric use Scrum to develop their hospital solutions.

IBM uses Scrum to manage the development of WebSphere, the most used Java platform for large Java application development.

Documentation does not determine the success or failure of Agile development. It certainly does not prevent or save an application's architecture from bad coding practices, nor does it stop the business pushing for more features then the team can sustainably develop.

Robin Dymond, CST Managing Partner, Innovel, LLC. www.innovel.net www.scrumtraining.com Americas: (804) 239-4329 twitter: @robindymond Linkedin: http://www.linkedin.com/in/leanagileexecutive On Sep 11, 2014 12:18 PM, "HABruce" notifications@github.com wrote:

I don't mean to seem argumentative...BUT Waiting for someone to complain and/or refusing to anticipate consumer needs doesn't really answer the learning loop (feedback) requirement for quality improvement. There is no doubt different consumers have different needs but it should be obvious which groups need what level of information...evidence of complaints by consumers is overwhelming...as is the efficacy of requesting documentation after the fact. As projects age (grow larger by accretion), planning constraints and design intent are easily lost on incremental developers who, in turn, contribute to a breakdown (rather than build-up of clarity and continuity (maintainability) of the code base. I could go on but I think you get the idea. I tend to see these government projects as having longer life cycles than personal use applications. For example, a quick survey of FDA documentation requirements should leave you with a clear understanding that process documentation is a fundamental requirement...much of it difficult (expensive) to produce after the fact. I happen to believe it's easier/smarter to get it as close to right as possible the first time...particularly if you accept the "good enough" premise upon which many (likely most) incremental, open source/agile projects depend. Just my opinion...you be the judge.

On 9/10/2014 9:06 PM, Robin Dymond wrote:

Documentation needs to have a clear consumer. If we don't have someone complaining that they need to read it, we are creating documents for no one, and that's pure waste.

Software developers generally know better than to rely on documents to describe what the software does. They can run tools to understand the structure and read code to understand what it does. Documentation is not a good way to describe what code does. Acceptance and unit Tests are better. Especially when they are automated.

Documentation needs consumers, and so user manuals, operations manuals, and help docs are useful. So are docs to meet regulatory needs, for example the FDA.

Robin Dymond, CST Managing Partner, Innovel, LLC. www.innovel.net www.scrumtraining.com Americas: (804) 239-4329 twitter: @robindymond Linkedin: http://www.linkedin.com/in/leanagileexecutive

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.

— Reply to this email directly or view it on GitHub https://github.com/WhiteHouse/playbook/issues/59.

— Reply to this email directly or view it on GitHub <https://github.com/WhiteHouse/playbook/issues/59#issuecomment-55206473 .

— Reply to this email directly or view it on GitHub https://github.com/WhiteHouse/playbook/issues/59#issuecomment-55313742.

[HABruce]

Possibly I don't understand the purpose of this exercise. The referenced use cases are unknown to me, however...what is not unknown to me is FDA Quality Systems, 21 CFR 820, Subpart A—General Provisions, §820.3 Definitions, (e) – (k) ...which states:

(e) Design history file(DHF) means a compilation of records which describes the design history of a finished device.

(f) Design input means the physical and performance requirements of a device that are used as a basis for device design.

(g) Design output means the results of a design effort at each design phase and at the end of the total design effort. The finished design output is the basis for the device master record. The total finished design output consists of the device, its packaging and labeling, and the device master record.

(h) Design review means a documented, comprehensive, systematic examination of a design to evaluate the adequacy of the design requirements, to evaluate the capability of the design to meet these requirements, and to identify problems.

(i) Device history record (DHR) means a compilation of records containing the production history of a finished device.

(j) Device master record (DMR) means a compilation of records containing the procedures and specifications for a finished device.

(k) Establish means define, document (in writing or electronically), and implement...

all of which clearly indicate an articulated record (documentation) of quality assurance for devices seeking FDA approval...from planning (design input) to implementation.

So you are quite right...it is not about opinion...in the case of FDA approval...or in my professional experience.

I am aware the average project contemplated by you Playbook and TechFAR folk will not be seeking FDA approval...however when trailblazing a new system...”Making knowledge transfer a priority from early planning through execution will assist the process at every level and is unlikely to occur without specification” … by this I meant that building-in Current Good Manufacturing Practice (CGMP) could automate much of the repetition/work of documentation by process (SCRUM or otherwise).

My area of concern is strictly medical and specifically where this organization intersects with Veteran's Affiars and the Evolution of VistA.

I brought this to the attention of the team an intention to collaborate on establishing policy, procedure and processes to broadly improve the artifacts that facilitate knowledge transfer...remain willing to discuss methods of improvement.

On 9/12/2014 1:48 AM, Robin Dymond wrote:

Fortunately I don't have to rely on opinion for this issue.

Client #1 uses Scrum for creating software to operate Pacemakers. They have significant FDA document requirements, and automated testing to prove every change is defect free. They have been using Scrum since 2008. Their is no more mission critical an application then running a pacemaker.

Client #2 uses Scrum with a product development division of over 400 people. Their product is a complete solution to operate a hospital. Over 1600 hospitals across Europe use their solution to do everything from schedule hospital beds to manage the Emergency room. The solution has been actively developed for 15 years. Their competitors in the USA, McKesson and General Electric use Scrum to develop their hospital solutions.

IBM uses Scrum to manage the development of WebSphere, the most used Java platform for large Java application development.

Documentation does not determine the success or failure of Agile development. It certainly does not prevent or save an application's architecture from bad coding practices, nor does it stop the business pushing for more features then the team can sustainably develop.

Robin Dymond, CST Managing Partner, Innovel, LLC. www.innovel.net www.scrumtraining.com Americas: (804) 239-4329 twitter: @robindymond Linkedin: http://www.linkedin.com/in/leanagileexecutive On Sep 11, 2014 12:18 PM, "HABruce" notifications@github.com wrote:

I don't mean to seem argumentative...BUT Waiting for someone to complain and/or refusing to anticipate consumer needs doesn't really answer the learning loop (feedback) requirement for quality improvement. There is no doubt different consumers have different needs but it should be obvious which groups need what level of information...evidence of complaints by consumers is overwhelming...as is the efficacy of requesting documentation after the fact. As projects age (grow larger by accretion), planning constraints and design intent are easily lost on incremental developers who, in turn, contribute to a breakdown (rather than build-up of clarity and continuity (maintainability) of the code base. I could go on but I think you get the idea. I tend to see these government projects as having longer life cycles than personal use applications. For example, a quick survey of FDA documentation requirements should leave you with a clear understanding that process documentation is a fundamental requirement...much of it difficult (expensive) to produce after the fact. I happen to believe it's easier/smarter to get it as close to right as possible the first time...particularly if you accept the "good enough" premise upon which many (likely most) incremental, open source/agile projects depend. Just my opinion...you be the judge.

On 9/10/2014 9:06 PM, Robin Dymond wrote:

Documentation needs to have a clear consumer. If we don't have someone complaining that they need to read it, we are creating documents for no one, and that's pure waste.

Software developers generally know better than to rely on documents to describe what the software does. They can run tools to understand the structure and read code to understand what it does. Documentation is not a good way to describe what code does. Acceptance and unit Tests are better. Especially when they are automated.

Documentation needs consumers, and so user manuals, operations manuals, and help docs are useful. So are docs to meet regulatory needs, for example the FDA.

Robin Dymond, CST Managing Partner, Innovel, LLC. www.innovel.net www.scrumtraining.com Americas: (804) 239-4329 twitter: @robindymond Linkedin: http://www.linkedin.com/in/leanagileexecutive

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.

— Reply to this email directly or view it on GitHub https://github.com/WhiteHouse/playbook/issues/59.

— Reply to this email directly or view it on GitHub

<https://github.com/WhiteHouse/playbook/issues/59#issuecomment-55206473 .

— Reply to this email directly or view it on GitHub

https://github.com/WhiteHouse/playbook/issues/59#issuecomment-55313742.

— Reply to this email directly or view it on GitHub https://github.com/WhiteHouse/playbook/issues/59#issuecomment-55364000.

[cew821]

We’d like to spend more time learning about this one. We think there is potential for a new play on knowledge transfer and sustaining services. Please continue to share references to best practices on how to determine the appropriate amount of documentation for digital services.

[rdymond1]

Hi Charles,

There are no best practices.

"[Best Practice] has a chilling effect on our progress as an intellectual craft when people pretend that a best practice exists. Best practice blather becomes a substitute for the more difficult, less glamorous, but ultimately more powerful idea of learning how to do your job. By “learning” I mean practicing the skills of identifying and solving patterns of problems we encounter"

See more at James Bach's blog on this topic. http://www.satisfice.com/blog/archives/27

cheers, Robin

Robin Dymond, CST Managing Partner, Innovel, LLC. www.innovel.net www.scrumtraining.com Americas: (804) 239-4329 Europe: +32 489 674 366 twitter: @robindymond Linkedin: http://www.linkedin.com/in/leanagileexecutive

On Wed, Sep 24, 2014 at 5:26 PM, Charles Worthington < notifications@github.com> wrote:

We’d like to spend more time learning about this one. We think there is potential for a new play on knowledge transfer and sustaining services. Please continue to share references to best practices on how to determine the appropriate amount of documentation for digital services.

— Reply to this email directly or view it on GitHub https://github.com/WhiteHouse/playbook/issues/59#issuecomment-56754453.

[HABruce]

WoW Robin,

Looks like you and I are simply bound to bump heads on this "sacrifice of discipline and rigor" thing. Unfortunately, I have run across this nihilistic rationalization a few times in the past...and seen it fail spectacularly and repeatedly. And it isn't that I don't love the concept...I do, I mean that...it just doesn't work because the argument oddly lacks awareness that its central thesis is tautological, itself a best practice...even while saying "NO best practices"... and for precisely the same reasons so eloquently presented. I believe I can accurately posit the fear of best practices is born of immutable, opaque processes with no quality feedback loop. I suggest curling up with a Demming book or two. The problems associated with square pegs/round holes is overcome by preserving (baking in) multiple back-channels for analysis and innovation which, quite naturally, must be empowered by transparent process to enforce well reasoned (and supported) improvements. It's a culture thing...respectful of reason (commitment and value expression)...documentation is the bridge upon which reason is threshed (through collaboration) in search of kernels (which may present as best practices)...and which, interestingly, become the status quo and open to further inquiry...lather, rinse, repeat. Otherwise, we are blinded by, in this case, faith in uniqueness and fated to remain blind because the pristine clarity of unchallenged (undocumented) thought, once given form in code or process, is immediately on its way to degradation as memory of the rationale fails and circumstance changes...not to mention subversion by hidden agenda...defeating transparency.

Attempting to perfect a lasting framework without an introspective loop is an exercise in futility. So let's transcend the obvious infinite loop, establish methods to challenge the provenance of accepted orthodoxy and move directly to context. Broadly applicable frameworks demand resilience and re-usability. Beginning with a conceptual foundation is essential...it could be as simple as a mission statement or as complex as a etiology...whatever it takes to establish and maintain the cultural imperative. It always comes down to people in the end. So let's agree to remain persuaded by reason, rigorous in our inquiry and disciplined in our approach. Killing off the concept of best practices is simply overkill...as might be overly prescriptive methods, thinly stretched over an application.

My sense of what we are trying to accomplish is a cultural sea-change...and much more inclusive than a recitation of fear-based adherence to total independence for the sake of inquiry. The next logical step is to place faith in our efforts and methods to ensure the status quo never becomes sacrosanct, discussion limited or decision processes secreted...to fully enable the thousand eyes.

On the other hand, I am sensitive to the burden of documentation. Clearly, I could be wrong here, but I interpret such articulated resistance as a kind of boundary dispute. In the open source context, agile processes require much of the participants...adding documentation to the menu of freely contributed services is clearly onerous. Eventually, this must be recognized as the central dilemma of open source...that attracting and retaining talent is a resource allocation issue...nothing is free....and I don't disagree with you on this even a little. Trying to keep documentation in the "paid work" category is a reasonable effort...but the timing is off. Much like the IRS has learned to collect tax in the attributable period (and it keeps getting shorter)...the quality of documentation is clearly tied to timing. If we intend to frame a transparent decision and quality improvement loop...then cultural value expression must remain an essential part of the knowledge transfer....if it no longer fits, it can be changed as well. The resource allocation discussion has already begun in the context of mission critical applications...beyond regulatory requirements. As such, it is reasonable to expect resource allocation for documentation in the improved acquisition process. Future generations will appreciate your thoughtful inclusion.

HAB

On 9/24/2014 10:58 PM, Robin Dymond wrote:

Hi Charles,

There are no best practices.

"[Best Practice] has a chilling effect on our progress as an intellectual craft when people pretend that a best practice exists. Best practice blather becomes a substitute for the more difficult, less glamorous, but ultimately more powerful idea of learning how to do your job. By “learning” I mean practicing the skills of identifying and solving patterns of problems we encounter"

See more at James Bach's blog on this topic. http://www.satisfice.com/blog/archives/27

cheers, Robin

Robin Dymond, CST Managing Partner, Innovel, LLC. www.innovel.net www.scrumtraining.com Americas: (804) 239-4329 Europe: +32 489 674 366 twitter: @robindymond Linkedin: http://www.linkedin.com/in/leanagileexecutive

On Wed, Sep 24, 2014 at 5:26 PM, Charles Worthington < notifications@github.com> wrote:

We’d like to spend more time learning about this one. We think there is potential for a new play on knowledge transfer and sustaining services. Please continue to share references to best practices on how to determine the appropriate amount of documentation for digital services.

— Reply to this email directly or view it on GitHub

https://github.com/WhiteHouse/playbook/issues/59#issuecomment-56754453.

— Reply to this email directly or view it on GitHub https://github.com/WhiteHouse/playbook/issues/59#issuecomment-56768024.

[HABruce]

Hey Charles,

Just a few lines on my way out the door...

I suggest a study of Edwards Demming's writings...maybe begin with "The Deming Management Method" for an overview...next might be "Out of the Crisis".

He's about culture building...the goal of knowledge transfer and change management.

However, if you are interested in FDA-type documentation requirements...please let me know and I'll forward the applicable authoritative literature.

I'm not sure where you want to go with this...I don't mean to be coy but I actually agree with Robin about best practices, in a large sense, for determining questions like the appropriate amount of documentation for digital services. You are trailblazing...establishing the requisite environment from which "best practices" can be derived, including back-channels to enable retrospective inquiry, is much more important than the opening estimate. Putting systems/methods in place that encourage rigorous collaboration for improvement will obviate whatever best guess you forward at the beginning. Some efforts require maturation such as broad participation and dedication to a process that establishes norms. I'm pretty sure this is one of them.

Multi-agent infrastructure projects are not a new concept. It is axiomatic that design/planning consistently meets cost:benefit expectations and articulated documentation artifacts of the process, cradle to grave, will yield insights for improvements and posterity. Likely this is also an area you will have to "best guess" in the beginning. If your process is transparent and accessible...conscious dedication to improvement will trend outcomes toward client satisfaction (both internal and external) as an extension of cultural values...AND make it much easier to incorporate additions, remediate shortcomings, interoperate data/systems, quantify TCO and predict budgetary requirements. What these systems will not do is populate themselves or function without trained and qualified personnel. Estimate accordingly in a sense of fairness to achieve sustainability.

I wrote in my reply to Robin that I consider "cultural value expression...an essential part of the knowledge transfer" because demonstrable values are the glue that bind culture. If you want/need people to follow you into the fray there is simply no substitute for conceptual clarity. I am very interested in change management...and I suspect this is near the heart of your primary challenge.

HAB

On 9/24/2014 7:26 PM, Charles Worthington wrote:

We’d like to spend more time learning about this one. We think there is potential for a new play on knowledge transfer and sustaining services. Please continue to share references to best practices on how to determine the appropriate amount of documentation for digital services.

— Reply to this email directly or view it on GitHub https://github.com/WhiteHouse/playbook/issues/59#issuecomment-56754453.

[rdymond1]

Hi Charles,

As mentioned in a couple places in HAB's missive, Agile methods rely on collaboration. So in Agile used for developing digital services, high bandwidth face to face communication over lossy low bandwidth documentation. Agile value is: Working software over comprehensive documentation The principles are: Use face to face communication wherever possible. Document only when you are sure the document is really valuable to someone, and you can go talk to them and ask them what they need (customer driven) The practices are: NA. Practices are what you do in your context. specifying specific documentation practices without context leads to wasted effort and doing the wrong thing. For example one context could be a traffic control system, another could be a health insurance exchange. Build your practices based on Agile values, principles and the specific context.

Thanks, Robin.

Robin Dymond, CST Managing Partner, Innovel, LLC. www.innovel.net www.scrumtraining.com Americas: (804) 239-4329 Europe: +32 489 674 366 twitter: @robindymond Linkedin: http://www.linkedin.com/in/leanagileexecutive

On Thu, Sep 25, 2014 at 5:36 AM, HABruce notifications@github.com wrote:

Hey Charles,

Just a few lines on my way out the door...

I suggest a study of Edwards Demming's writings...maybe begin with "The Deming Management Method" for an overview...next might be "Out of the Crisis".

He's about culture building...the goal of knowledge transfer and change management.

However, if you are interested in FDA-type documentation requirements...please let me know and I'll forward the applicable authoritative literature.

I'm not sure where you want to go with this...I don't mean to be coy but I actually agree with Robin about best practices, in a large sense, for determining questions like the appropriate amount of documentation for digital services. You are trailblazing...establishing the requisite environment from which "best practices" can be derived, including back-channels to enable retrospective inquiry, is much more important than the opening estimate. Putting systems/methods in place that encourage rigorous collaboration for improvement will obviate whatever best guess you forward at the beginning. Some efforts require maturation such as broad participation and dedication to a process that establishes norms. I'm pretty sure this is one of them.

Multi-agent infrastructure projects are not a new concept. It is axiomatic that design/planning consistently meets cost:benefit expectations and articulated documentation artifacts of the process, cradle to grave, will yield insights for improvements and posterity. Likely this is also an area you will have to "best guess" in the beginning. If your process is transparent and accessible...conscious dedication to improvement will trend outcomes toward client satisfaction (both internal and external) as an extension of cultural values...AND make it much easier to incorporate additions, remediate shortcomings, interoperate data/systems, quantify TCO and predict budgetary requirements. What these systems will not do is populate themselves or function without trained and qualified personnel. Estimate accordingly in a sense of fairness to achieve sustainability.

I wrote in my reply to Robin that I consider "cultural value expression...an essential part of the knowledge transfer" because demonstrable values are the glue that bind culture. If you want/need people to follow you into the fray there is simply no substitute for conceptual clarity. I am very interested in change management...and I suspect this is near the heart of your primary challenge.

HAB

On 9/24/2014 7:26 PM, Charles Worthington wrote:

We’d like to spend more time learning about this one. We think there is potential for a new play on knowledge transfer and sustaining services. Please continue to share references to best practices on how to determine the appropriate amount of documentation for digital services.

— Reply to this email directly or view it on GitHub <https://github.com/WhiteHouse/playbook/issues/59#issuecomment-56754453 .

— Reply to this email directly or view it on GitHub https://github.com/WhiteHouse/playbook/issues/59#issuecomment-56806368.

[HABruce]

Sorry for my late response...once again, I am forced to agree with Robin about agile methods...

The difference between banging out a coded product and developing usable, reusable, maintainable, resilient, measurable, etc. systems is AKA: Design intent. It is not by chance that I commented at documentation. There is a purposeful tension between coders and management (and on up and down the line)...no reason to illustrate beyond pointing out the interplay between job descriptions is a balancing mechanism among driving forces. Clearly, if developers drive the claim they can't/don't know what they need until they get there, then everyone in their path may reasonably be expected to share the same position...by design. An unknowing asking an uninformed about an unknowable is supercilious....a dodge at best. I'm pretty sure this executive effort is not about worship at the altar of AGILE...it's about aligning acquisitions with working alternatives to the failures of predecessors...with a measure of prescience. I advocate learning systems (inclusive collaboration), discipline and rigor.

I would expect someone in Robin's position to take a similar tack, however the real question is what does someone in your position do? or better yet someone in your boss's position? or your boss's boss? I ask this question because I can provide several examples of spectacular failures where this simple question remains a question...judging by outcome...it is not a given. From the top down, what mission parameter, precisely, is preserved by such an argument - that no communication is preferable to lossy beyond a certain point? Having successfully killed off planning and communication at the outset...what other rationalizations can be accepted before purposeful is wholly lost? There has been no suggestion that coders have to interrupt their groove to explain themselves...only that process features be put in place to ensure the value chain...think of it as risk management responsive to lifecycle concerns...development (pick your style) is a small, but capital intensive piece of the timeline that effectively determines the fully absorbed TCO (pick your model).

Learning (accreted) systems are not new...nor are difficult problems. Engineers and Architects have evolved learning systems for more than a hundred years. Discipline and communication are central to their processes. From the bottom up, how many times will the user pay to train or devolve the coded artifact? How much might be saved by the clarity of exposing the process (cradle to grave - planning, design compile and run-time) to collaboration/documentation before, during and after it is cast it in code? I can imagine no benefit to opaque processes. Properly organized...the more the merrier. Sure, someone might argue needle in the haystack, but the more likely problem will be the missing needle. No one likes documentation...but it is a characteristic of maturity, discipline and rigor...valuable for training and understanding...essential for retrospective inquiry/evaluation...the learning loop.

I've reached the end of the evaluation process in the absence of specific questions. If the group is seriously considering adding to the Playbook...then I submit it's time to start getting specific about mission and context. Not sure how many of the group are familiar with the Clinger Cohen Enterprise Architecture Assessment Framework, et al. It is a prime example of opaque, non-collaborative, unquestioned methodology. A great study model for "unintended consequences"...apparently bereft of retrospective inquiry...a testimony to the need for independent participation...and how to destroy efficacy with top-down dominated make-work. Check it out...its worth the price of admission.

HAB

On 9/25/2014 11:29 AM, Robin Dymond wrote:

Hi Charles,

As mentioned in a couple places in HAB's missive, Agile methods rely on collaboration. So in Agile used for developing digital services, high bandwidth face to face communication over lossy low bandwidth documentation. Agile value is: Working software over comprehensive documentation The principles are: Use face to face communication wherever possible. Document only when you are sure the document is really valuable to someone, and you can go talk to them and ask them what they need (customer driven) The practices are: NA. Practices are what you do in your context. specifying specific documentation practices without context leads to wasted effort and doing the wrong thing. For example one context could be a traffic control system, another could be a health insurance exchange. Build your practices based on Agile values, principles and the specific context.

Thanks, Robin.

Robin Dymond, CST Managing Partner, Innovel, LLC. www.innovel.net www.scrumtraining.com Americas: (804) 239-4329 Europe: +32 489 674 366 twitter: @robindymond Linkedin: http://www.linkedin.com/in/leanagileexecutive

On Thu, Sep 25, 2014 at 5:36 AM, HABruce notifications@github.com wrote:

Hey Charles,

Just a few lines on my way out the door...

I suggest a study of Edwards Demming's writings...maybe begin with "The Deming Management Method" for an overview...next might be "Out of the Crisis".

He's about culture building...the goal of knowledge transfer and change management.

However, if you are interested in FDA-type documentation requirements...please let me know and I'll forward the applicable authoritative literature.

I'm not sure where you want to go with this...I don't mean to be coy but I actually agree with Robin about best practices, in a large sense, for determining questions like the appropriate amount of documentation for digital services. You are trailblazing...establishing the requisite environment from which "best practices" can be derived, including back-channels to enable retrospective inquiry, is much more important than the opening estimate. Putting systems/methods in place that encourage rigorous collaboration for improvement will obviate whatever best guess you forward at the beginning. Some efforts require maturation such as broad participation and dedication to a process that establishes norms. I'm pretty sure this is one of them.

Multi-agent infrastructure projects are not a new concept. It is axiomatic that design/planning consistently meets cost:benefit expectations and articulated documentation artifacts of the process, cradle to grave, will yield insights for improvements and posterity. Likely this is also an area you will have to "best guess" in the beginning. If your process is transparent and accessible...conscious dedication to improvement will trend outcomes toward client satisfaction (both internal and external) as an extension of cultural values...AND make it much easier to incorporate additions, remediate shortcomings, interoperate data/systems, quantify TCO and predict budgetary requirements. What these systems will not do is populate themselves or function without trained and qualified personnel. Estimate accordingly in a sense of fairness to achieve sustainability.

I wrote in my reply to Robin that I consider "cultural value expression...an essential part of the knowledge transfer" because demonstrable values are the glue that bind culture. If you want/need people to follow you into the fray there is simply no substitute for conceptual clarity. I am very interested in change management...and I suspect this is near the heart of your primary challenge.

HAB

On 9/24/2014 7:26 PM, Charles Worthington wrote:

We’d like to spend more time learning about this one. We think there is potential for a new play on knowledge transfer and sustaining services. Please continue to share references to best practices on how to determine the appropriate amount of documentation for digital services.

— Reply to this email directly or view it on GitHub

<https://github.com/WhiteHouse/playbook/issues/59#issuecomment-56754453 .

— Reply to this email directly or view it on GitHub

https://github.com/WhiteHouse/playbook/issues/59#issuecomment-56806368.

— Reply to this email directly or view it on GitHub https://github.com/WhiteHouse/playbook/issues/59#issuecomment-56836194.

[rdymond1]

I am bowing out of this conversation. It has become unproductive. As with all change processes one encounters resistance to change, as we see here.

Robin Dymond, CST Managing Partner, Innovel, LLC. www.innovel.net www.scrumtraining.com Americas: (804) 239-4329 Europe: +32 489 674 366 twitter: @robindymond Linkedin: http://www.linkedin.com/in/leanagileexecutive

On Thu, Sep 25, 2014 at 5:12 PM, HABruce notifications@github.com wrote:

Sorry for my late response...once again, I am forced to agree with Robin about agile methods...

The difference between banging out a coded product and developing usable, reusable, maintainable, resilient, measurable, etc. systems is AKA: Design intent. It is not by chance that I commented at documentation. There is a purposeful tension between coders and management (and on up and down the line)...no reason to illustrate beyond pointing out the interplay between job descriptions is a balancing mechanism among driving forces. Clearly, if developers drive the claim they can't/don't know what they need until they get there, then everyone in their path may reasonably be expected to share the same position...by design. An unknowing asking an uninformed about an unknowable is supercilious....a dodge at best. I'm pretty sure this executive effort is not about worship at the altar of AGILE...it's about aligning acquisitions with working alternatives to the failures of predecessors...with a measure of prescience. I advocate learning systems (inclusive collaboration), discipline and rigor.

I would expect someone in Robin's position to take a similar tack, however the real question is what does someone in your position do? or better yet someone in your boss's position? or your boss's boss? I ask this question because I can provide several examples of spectacular failures where this simple question remains a question...judging by outcome...it is not a given. From the top down, what mission parameter, precisely, is preserved by such an argument - that no communication is preferable to lossy beyond a certain point? Having successfully killed off planning and communication at the outset...what other rationalizations can be accepted before purposeful is wholly lost? There has been no suggestion that coders have to interrupt their groove to explain themselves...only that process features be put in place to ensure the value chain...think of it as risk management responsive to lifecycle concerns...development (pick your style) is a small, but capital intensive piece of the timeline that effectively determines the fully absorbed TCO (pick your model).

Learning (accreted) systems are not new...nor are difficult problems. Engineers and Architects have evolved learning systems for more than a hundred years. Discipline and communication are central to their processes. From the bottom up, how many times will the user pay to train or devolve the coded artifact? How much might be saved by the clarity of exposing the process (cradle to grave - planning, design compile and run-time) to collaboration/documentation before, during and after it is cast it in code? I can imagine no benefit to opaque processes. Properly organized...the more the merrier. Sure, someone might argue needle in the haystack, but the more likely problem will be the missing needle. No one likes documentation...but it is a characteristic of maturity, discipline and rigor...valuable for training and understanding...essential for retrospective inquiry/evaluation...the learning loop.

I've reached the end of the evaluation process in the absence of specific questions. If the group is seriously considering adding to the Playbook...then I submit it's time to start getting specific about mission and context. Not sure how many of the group are familiar with the Clinger Cohen Enterprise Architecture Assessment Framework, et al. It is a prime example of opaque, non-collaborative, unquestioned methodology. A great study model for "unintended consequences"...apparently bereft of retrospective inquiry...a testimony to the need for independent participation...and how to destroy efficacy with top-down dominated make-work. Check it out...its worth the price of admission.

HAB

On 9/25/2014 11:29 AM, Robin Dymond wrote:

Hi Charles,

As mentioned in a couple places in HAB's missive, Agile methods rely on collaboration. So in Agile used for developing digital services, high bandwidth face to face communication over lossy low bandwidth documentation. Agile value is: Working software over comprehensive documentation The principles are: Use face to face communication wherever possible. Document only when you are sure the document is really valuable to someone, and you can go talk to them and ask them what they need (customer driven) The practices are: NA. Practices are what you do in your context. specifying specific documentation practices without context leads to wasted effort and doing the wrong thing. For example one context could be a traffic control system, another could be a health insurance exchange. Build your practices based on Agile values, principles and the specific context.

Thanks, Robin.

Robin Dymond, CST Managing Partner, Innovel, LLC. www.innovel.net www.scrumtraining.com Americas: (804) 239-4329 Europe: +32 489 674 366 twitter: @robindymond Linkedin: http://www.linkedin.com/in/leanagileexecutive

On Thu, Sep 25, 2014 at 5:36 AM, HABruce notifications@github.com wrote:

Hey Charles,

Just a few lines on my way out the door...

I suggest a study of Edwards Demming's writings...maybe begin with "The Deming Management Method" for an overview...next might be "Out of the Crisis".

He's about culture building...the goal of knowledge transfer and change management.

However, if you are interested in FDA-type documentation requirements...please let me know and I'll forward the applicable authoritative literature.

I'm not sure where you want to go with this...I don't mean to be coy but I actually agree with Robin about best practices, in a large sense, for determining questions like the appropriate amount of documentation for digital services. You are trailblazing...establishing the requisite environment from which "best practices" can be derived, including back-channels to enable retrospective inquiry, is much more important than the opening estimate. Putting systems/methods in place that encourage rigorous collaboration for improvement will obviate whatever best guess you forward at the beginning. Some efforts require maturation such as broad participation and dedication to a process that establishes norms. I'm pretty sure this is one of them.

Multi-agent infrastructure projects are not a new concept. It is axiomatic that design/planning consistently meets cost:benefit expectations and articulated documentation artifacts of the process, cradle to grave, will yield insights for improvements and posterity. Likely this is also an area you will have to "best guess" in the beginning. If your process is transparent and accessible...conscious dedication to improvement will trend outcomes toward client satisfaction (both internal and external) as an extension of cultural values...AND make it much easier to incorporate additions, remediate shortcomings, interoperate data/systems, quantify TCO and predict budgetary requirements. What these systems will not do is populate themselves or function without trained and qualified personnel. Estimate accordingly in a sense of fairness to achieve sustainability.

I wrote in my reply to Robin that I consider "cultural value expression...an essential part of the knowledge transfer" because demonstrable values are the glue that bind culture. If you want/need people to follow you into the fray there is simply no substitute for conceptual clarity. I am very interested in change management...and I suspect this is near the heart of your primary challenge.

HAB

On 9/24/2014 7:26 PM, Charles Worthington wrote:

We’d like to spend more time learning about this one. We think there is potential for a new play on knowledge transfer and sustaining services. Please continue to share references to best practices on how to determine the appropriate amount of documentation for digital services.

— Reply to this email directly or view it on GitHub

<https://github.com/WhiteHouse/playbook/issues/59#issuecomment-56754453 .

— Reply to this email directly or view it on GitHub

<https://github.com/WhiteHouse/playbook/issues/59#issuecomment-56806368 .

— Reply to this email directly or view it on GitHub <https://github.com/WhiteHouse/playbook/issues/59#issuecomment-56836194 .

— Reply to this email directly or view it on GitHub https://github.com/WhiteHouse/playbook/issues/59#issuecomment-56898138.

[bewest]

Howdy, I've been searching for open source systems that are also documented with 820 in mind.

Rather than enforce changes on contributors, I'm going to attempt simply describing how social networks like github works, eg how the culture of safety works and develops. For the sections @HABruce mentions, I plan on saying, see "git flow" and github materials, changelogs, pull requests. Then in audits, reporting, I plan on using a tool to mine the data and usage trails from the APIs github and other systems make available. Ideally, the audit trails should help observing whether or not the process was followed, as well as how effective it was.

In particular, a tool could use github's API to export weekly/monthly roll ups on issues closed/opened. The issues themselves could be design discussions closed/opened as design inputs, with pull requests, and the discussions on pull requests archiving the review. Is anyone attempting to use APIs to observe and document requirements to fulfill CFR 820? Is VISTA using git-flow? Does VISTA have an open set of documents to satisfy 820 et al?

http://process-controls.readthedocs.org/en/latest/index.html

[HABruce]

Hello Ben, I'd enjoy seeing your output...please post links. I would remind you that, much like buying computers, it may not pay off to definitively explore waning systems for medical applications (and devices)...like the FDAs 21 CFR 820, et al. I would refer you to the IOM'S 2011 Health IT and Patient safety as a potentially useful (think predictive) guidebook for regulatory schema...with particular attention to the differences between current FDA's approach to regulatory architecture as compared to ISO's...and their comparative efficacy as well. Despite dissent, the published Classification changes appear to have won the day for this planning cycle but standards and principles may be the coming quality reporting system of choice for all but Class III devices (which appears to be on a longer sunset timetable). In my mind...Safety is a close proxy for knowledge transfer in this environment...particularly in this context...as the lion's share of development and testing in the foreseeable future will be in Class I and II...with testing and defensive metrics of comparative effectivness the new rubicon in Class I & 2...particularly for OS contributions. To answer your question...the VA pioneered the development of Healthcare Failure Modes and Effects Analysis (HFMEA) and trademarked it for use in barcode and medication administration (think MAR)...low fault tolerance environments. The VA also developed 2 complimentary reporting systems ...the external NASA/VA Patient Safety Reporting System and the internal VA National Center for Patient Safety reporting system. I will have to check if the code is available for the reporting systems...but barcode is if you can use the platform. Sorry for the smattering but I don't know what you are specifically trying to accomplish...but you have picked an area of intense interest (at the moment). You seem to be working toward classification rather than reporting so I am guessing you are concerned with retroactive application of good (quality) manufacturing practices...which could be considered settled for the time being. However effectiveness is of ongoing concern...particularly as new metrics are identified. How much is enough remains to be seen...hopefully only in the short term. Unfortunately, the unlucky few to establish precedents will have most likely crossed the "intended use" threshold...in which case they will want to be as close as possible...which will require close tracking of the publications of (now) several agencies and offices. This is particularly what I believe should not be left to chance... affirmatively or otherwise. The sooner we get to "learning systems of the socio-technical environment as described by the IOM...the better I'll like it. Could be an API roll-up of a dev site will be "enough" but that is a matter of opinion...mostly a judge's. I remain professionally skeptical. I realize your motto is "we are not waiting"...but product liability is very real. Very interested in the FDA's take on an OS Class III device in an number of areas. Please keep me informed...best of luck...Hope this helps. HABruce I have to wonder if you could suggest an ISO process and get pre-market approval...it seems to fit an OS process better.

On 1/21/2015 8:54 PM, Ben West wrote:

Howdy, I've been searching for open source systems that are also documented with 820 in mind.

Rather than enforce changes on contributors, I'm going to attempt simply describing how social networks like github works, eg how the culture of safety works and develops. For the sections @HABruce https://github.com/HABruce mentions, I plan on saying, see "git flow" and github materials, changelogs, pull requests. Then in audits, reporting, I plan on using a tool to mine the data and usage trails from the APIs github and other systems make available. Ideally, the audit trails should help observing whether or not the process was followed, as well as how effective it was.

In particular, a tool could use github's API to export weekly/monthly roll ups on issues closed/opened. The issues themselves could be design discussions closed/opened as design inputs, with pull requests, and the discussions on pull requests archiving the review. Is anyone attempting to use APIs to observe and document requirements to fulfill CFR 820? Is VISTA using git-flow? Does VISTA have an open set of documents to satisfy 820 et al?

http://process-controls.readthedocs.org/en/latest/index.html

— Reply to this email directly or view it on GitHub https://github.com/WhiteHouse/playbook/issues/59#issuecomment-70958859.

[wvchris]

Although I have been a member for a while, I haven't spoken up. I am interested in GT.M V6.3. It has been announced as released, but hasn't made available. I suspect that their intensive testing has revealed something that caused the release to be delayed. For our testing and development purposes, we could probably benefit from seeing the current version and concerns list and aid in helping to make this release stronger and more resilient.

[bewest]

Howdy @HABruce, been a long time. Since we last chatted, FDA invented PJT product code for secondary display of glucose data, which fit's Nightscout's use cases like a glove, almost made-to-fit, I'm sure with Dexcom's support. Since then, I've moved onto to https://github.com/openaps/openaps. Also since then, usds has matured quite a bit, FDA has things like openfda, and Susannah Fox has publically called out the wearenotwaiting movement as something to support. Openaps was praised in a conversation a few weeks ago with President Obama.

It's been quite an interesting journey...