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
#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
#59.

—
Reply to this email directly or view it on GitHub
#59 (comment).

[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
#59 (comment).

[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
#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
#59.

—
Reply to this email directly or view it on GitHub
#59 (comment).

[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
#59.

—
Reply to this email directly or view it on GitHub
<#59 (comment)
.

—
Reply to this email directly or view it on GitHub
#59 (comment).

[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
#59.

—
Reply to this email directly or view it on GitHub

<#59 (comment)
.

—
Reply to this email directly or view it on GitHub

#59 (comment).

—
Reply to this email directly or view it on GitHub
#59 (comment).

[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
#59 (comment).

[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

#59 (comment).

—
Reply to this email directly or view it on GitHub
#59 (comment).

[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
#59 (comment).

[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
<#59 (comment)
.

—
Reply to this email directly or view it on GitHub
#59 (comment).

[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

<#59 (comment)
.

—
Reply to this email directly or view it on GitHub

#59 (comment).

—
Reply to this email directly or view it on GitHub
#59 (comment).

[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

<#59 (comment)
.

—
Reply to this email directly or view it on GitHub

<#59 (comment)
.

—
Reply to this email directly or view it on GitHub
<#59 (comment)
.

—
Reply to this email directly or view it on GitHub
#59 (comment).

[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
#59 (comment).

[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...