SlideShare a Scribd company logo

The Elusive Nature of Software Documentation

M
M
Margaret-Anne StoreyProfessor of Computer Science at University of Victoria

Keynote at ICSME 2017, Shanghai, China. Title: The Elusive Nature of Software Documentation and Why Understanding How Knowledge Flows Matters Abstract: Many developers consider writing documentation to be a painful and under-appreciated activity, yet the same developers often complain that a lack of documentation significantly hampers their work. Other developers argue that documentation is passé as developers more readily curate and exchange knowledge through networked platforms such as Slack, Twitter, and Stack Overflow. And while the savvy modern developer will know who to follow, who to ask, and where to look when they need software knowledge, finding the right knowledge at the right time remains a serious development bottleneck for many. Recognizing that these platforms contain golden nuggets of useful information, we see tremendous effort being directed at designing methods for capturing, mining, extracting, and distributing software knowledge, but will they succeed if we lack a good understanding of how knowledge flows in software development projects and communities? Through this talk, I will discuss the elusive nature of documentation and why I believe documentation will always be hard to define, capture, distribute, keep up to date, and to find, and I will argue that we should focus more on understanding, supporting, and amplifying knowledge flow in distributed software development.

The Elusive Nature of Software Documentation

1 of 55
Download to read offline
The Elusive Nature of
Software Documentation
And	Why	Understanding	How	
Knowledge Flows	Matters
Margaret-Anne Storey
@margaretstorey
What happens when
documentation is elusive!
“I,	Pencil”,	An	essay	by	Leonard	Read,	1958
“Simple?
Yet, not a single person on the face of this earth knows how to make me”
“At some point, human intelligence became
collective and cumulative in a way that happened
to no other animal”
― Matt Ridley, The Rational Optimist
The role of knowledge in software development
• Insights are more important assets than program text
• Designers need to share theories of the problem and
solution domain, not the design of the code
• Much of these insights are “tacit” knowledge
• No one person or team can understand everything about a
technology
"Programming as theory building”, Peter Naur, 1985.
Itinerary...
• How development knowledge flows and how it is created
• Challenges faced in knowledge flow
(externalization, communication, onboarding)
• Goals for improving knowledge flow
(documentation, creativity, learning)
• Enablers
(automation, culture, rewards, knowledge routes, specialization)
• An idea!
Knowledge
creation
model:
Nonaka, Ikujiro; Takeuchi, Hirotaka (1995), The knowledge creating
company: how Japanese companies create the dynamics of innovation,
New York: Oxford University Press, p. 284, ISBN 978-0-19-509269-1
“We can know more
than we can tell”
Polanyi, 1966

Recommended

The (R)evolution of Social Media in Software Engineering
The (R)evolution of Social Media in Software EngineeringThe (R)evolution of Social Media in Software Engineering
The (R)evolution of Social Media in Software EngineeringMargaret-Anne Storey
 
Crowdsourcing Documentation in Software Engineering
Crowdsourcing Documentation in Software EngineeringCrowdsourcing Documentation in Software Engineering
Crowdsourcing Documentation in Software EngineeringMargaret-Anne Storey
 
FSE 2016 Panel: The State of Software Engineering Research
FSE 2016 Panel: The State of Software Engineering ResearchFSE 2016 Panel: The State of Software Engineering Research
FSE 2016 Panel: The State of Software Engineering ResearchMargaret-Anne Storey
 
Towards the Social Programmer (MSR 2012 Keynote by M. Storey)
Towards the Social Programmer (MSR 2012 Keynote by M. Storey)Towards the Social Programmer (MSR 2012 Keynote by M. Storey)
Towards the Social Programmer (MSR 2012 Keynote by M. Storey)Margaret-Anne Storey
 
Components license
Components licenseComponents license
Components licensedmgerman
 
Personal dashboards for individual learning and project awareness in social s...
Personal dashboards for individual learning and project awareness in social s...Personal dashboards for individual learning and project awareness in social s...
Personal dashboards for individual learning and project awareness in social s...Wolfgang Reinhardt
 
Open Collaboration and Peer Production: Technical Infrastructure and Communit...
Open Collaboration and Peer Production: Technical Infrastructure and Communit...Open Collaboration and Peer Production: Technical Infrastructure and Communit...
Open Collaboration and Peer Production: Technical Infrastructure and Communit...Sebastian Benthall
 
SOLARSPELL: THE SOLAR POWERED EDUCATIONAL LEARNING LIBRARY - EXPERIENTIAL LEA...
SOLARSPELL: THE SOLAR POWERED EDUCATIONAL LEARNING LIBRARY - EXPERIENTIAL LEA...SOLARSPELL: THE SOLAR POWERED EDUCATIONAL LEARNING LIBRARY - EXPERIENTIAL LEA...
SOLARSPELL: THE SOLAR POWERED EDUCATIONAL LEARNING LIBRARY - EXPERIENTIAL LEA...Micah Altman
 

More Related Content

What's hot

What's On the Technology Horizon?
What's On the Technology Horizon?What's On the Technology Horizon?
What's On the Technology Horizon?lisbk
 
Lecture 3: Human-Computer Interaction: HCI Design (2014)
Lecture 3: Human-Computer Interaction: HCI Design (2014)Lecture 3: Human-Computer Interaction: HCI Design (2014)
Lecture 3: Human-Computer Interaction: HCI Design (2014)Lora Aroyo
 
Lecture 3: Vocabularies & Data Formats on the Social Web (2014)
Lecture 3: Vocabularies & Data Formats on the Social Web (2014)Lecture 3: Vocabularies & Data Formats on the Social Web (2014)
Lecture 3: Vocabularies & Data Formats on the Social Web (2014)Lora Aroyo
 
Lecture 2: Human-Computer Interaction: Conceptual Design (2014)
Lecture 2: Human-Computer Interaction: Conceptual Design (2014)Lecture 2: Human-Computer Interaction: Conceptual Design (2014)
Lecture 2: Human-Computer Interaction: Conceptual Design (2014)Lora Aroyo
 
Lecture 1: Social Web Introduction (2014)
Lecture 1: Social Web Introduction (2014)Lecture 1: Social Web Introduction (2014)
Lecture 1: Social Web Introduction (2014)Lora Aroyo
 
Lecture 5: Personalization on the Social Web (2014)
Lecture 5: Personalization on the Social Web (2014)Lecture 5: Personalization on the Social Web (2014)
Lecture 5: Personalization on the Social Web (2014)Lora Aroyo
 
MIT Program on Information Science Talk -- Julia Flanders on Jobs, Roles, Ski...
MIT Program on Information Science Talk -- Julia Flanders on Jobs, Roles, Ski...MIT Program on Information Science Talk -- Julia Flanders on Jobs, Roles, Ski...
MIT Program on Information Science Talk -- Julia Flanders on Jobs, Roles, Ski...Micah Altman
 
How to Stem Knowledge Loss, LegalIT Conference, Montreal April 2011
How to Stem Knowledge Loss, LegalIT Conference, Montreal April 2011How to Stem Knowledge Loss, LegalIT Conference, Montreal April 2011
How to Stem Knowledge Loss, LegalIT Conference, Montreal April 2011Gordon Ross
 
Welcome to User Experience (UX) Design at EMBL-EBI
Welcome to User Experience (UX) Design at EMBL-EBI Welcome to User Experience (UX) Design at EMBL-EBI
Welcome to User Experience (UX) Design at EMBL-EBI EMBL-EBI Web Development
 
Picturing the Social: Talk for Transforming Digital Methods Winter School
Picturing the Social: Talk for Transforming Digital Methods Winter SchoolPicturing the Social: Talk for Transforming Digital Methods Winter School
Picturing the Social: Talk for Transforming Digital Methods Winter SchoolFarida Vis
 
The evolution of research on social media
The evolution of research on social mediaThe evolution of research on social media
The evolution of research on social mediaFarida Vis
 
ESRC Research Methods Festival - From Flickr to Snapchat: The challenge of an...
ESRC Research Methods Festival - From Flickr to Snapchat: The challenge of an...ESRC Research Methods Festival - From Flickr to Snapchat: The challenge of an...
ESRC Research Methods Festival - From Flickr to Snapchat: The challenge of an...Farida Vis
 
Data excellence: Better data for better AI
Data excellence: Better data for better AIData excellence: Better data for better AI
Data excellence: Better data for better AILora Aroyo
 
Communication between open source developers
Communication between open source developersCommunication between open source developers
Communication between open source developersAlexander Serebrenik
 
Virtual Network Building: Connecting Trauma Experts Through Collaboration Tools
Virtual Network Building: Connecting Trauma Experts Through Collaboration Tools Virtual Network Building: Connecting Trauma Experts Through Collaboration Tools
Virtual Network Building: Connecting Trauma Experts Through Collaboration Tools Nathalie Reid
 
The Key Success Factor in Knowledge Management... What Else? Change Management
The Key Success Factor in Knowledge Management... What Else? Change ManagementThe Key Success Factor in Knowledge Management... What Else? Change Management
The Key Success Factor in Knowledge Management... What Else? Change ManagementPatti Anklam
 
Towards Contested Collective Intelligence
Towards Contested Collective IntelligenceTowards Contested Collective Intelligence
Towards Contested Collective IntelligenceSimon Buckingham Shum
 
Lecture 2: Interactions, Frameworks, Privacy & Security on the Social Web (2014)
Lecture 2: Interactions, Frameworks, Privacy & Security on the Social Web (2014)Lecture 2: Interactions, Frameworks, Privacy & Security on the Social Web (2014)
Lecture 2: Interactions, Frameworks, Privacy & Security on the Social Web (2014)Lora Aroyo
 
How Social Software Supports Cooperative Practices in a Globally Distributed ...
How Social Software Supports Cooperative Practices in a Globally Distributed ...How Social Software Supports Cooperative Practices in a Globally Distributed ...
How Social Software Supports Cooperative Practices in a Globally Distributed ...Rosalba Giuffrida
 

What's hot (20)

What's On the Technology Horizon?
What's On the Technology Horizon?What's On the Technology Horizon?
What's On the Technology Horizon?
 
Making ESSENCE Work
Making ESSENCE WorkMaking ESSENCE Work
Making ESSENCE Work
 
Lecture 3: Human-Computer Interaction: HCI Design (2014)
Lecture 3: Human-Computer Interaction: HCI Design (2014)Lecture 3: Human-Computer Interaction: HCI Design (2014)
Lecture 3: Human-Computer Interaction: HCI Design (2014)
 
Lecture 3: Vocabularies & Data Formats on the Social Web (2014)
Lecture 3: Vocabularies & Data Formats on the Social Web (2014)Lecture 3: Vocabularies & Data Formats on the Social Web (2014)
Lecture 3: Vocabularies & Data Formats on the Social Web (2014)
 
Lecture 2: Human-Computer Interaction: Conceptual Design (2014)
Lecture 2: Human-Computer Interaction: Conceptual Design (2014)Lecture 2: Human-Computer Interaction: Conceptual Design (2014)
Lecture 2: Human-Computer Interaction: Conceptual Design (2014)
 
Lecture 1: Social Web Introduction (2014)
Lecture 1: Social Web Introduction (2014)Lecture 1: Social Web Introduction (2014)
Lecture 1: Social Web Introduction (2014)
 
Lecture 5: Personalization on the Social Web (2014)
Lecture 5: Personalization on the Social Web (2014)Lecture 5: Personalization on the Social Web (2014)
Lecture 5: Personalization on the Social Web (2014)
 
MIT Program on Information Science Talk -- Julia Flanders on Jobs, Roles, Ski...
MIT Program on Information Science Talk -- Julia Flanders on Jobs, Roles, Ski...MIT Program on Information Science Talk -- Julia Flanders on Jobs, Roles, Ski...
MIT Program on Information Science Talk -- Julia Flanders on Jobs, Roles, Ski...
 
How to Stem Knowledge Loss, LegalIT Conference, Montreal April 2011
How to Stem Knowledge Loss, LegalIT Conference, Montreal April 2011How to Stem Knowledge Loss, LegalIT Conference, Montreal April 2011
How to Stem Knowledge Loss, LegalIT Conference, Montreal April 2011
 
Welcome to User Experience (UX) Design at EMBL-EBI
Welcome to User Experience (UX) Design at EMBL-EBI Welcome to User Experience (UX) Design at EMBL-EBI
Welcome to User Experience (UX) Design at EMBL-EBI
 
Picturing the Social: Talk for Transforming Digital Methods Winter School
Picturing the Social: Talk for Transforming Digital Methods Winter SchoolPicturing the Social: Talk for Transforming Digital Methods Winter School
Picturing the Social: Talk for Transforming Digital Methods Winter School
 
The evolution of research on social media
The evolution of research on social mediaThe evolution of research on social media
The evolution of research on social media
 
ESRC Research Methods Festival - From Flickr to Snapchat: The challenge of an...
ESRC Research Methods Festival - From Flickr to Snapchat: The challenge of an...ESRC Research Methods Festival - From Flickr to Snapchat: The challenge of an...
ESRC Research Methods Festival - From Flickr to Snapchat: The challenge of an...
 
Data excellence: Better data for better AI
Data excellence: Better data for better AIData excellence: Better data for better AI
Data excellence: Better data for better AI
 
Communication between open source developers
Communication between open source developersCommunication between open source developers
Communication between open source developers
 
Virtual Network Building: Connecting Trauma Experts Through Collaboration Tools
Virtual Network Building: Connecting Trauma Experts Through Collaboration Tools Virtual Network Building: Connecting Trauma Experts Through Collaboration Tools
Virtual Network Building: Connecting Trauma Experts Through Collaboration Tools
 
The Key Success Factor in Knowledge Management... What Else? Change Management
The Key Success Factor in Knowledge Management... What Else? Change ManagementThe Key Success Factor in Knowledge Management... What Else? Change Management
The Key Success Factor in Knowledge Management... What Else? Change Management
 
Towards Contested Collective Intelligence
Towards Contested Collective IntelligenceTowards Contested Collective Intelligence
Towards Contested Collective Intelligence
 
Lecture 2: Interactions, Frameworks, Privacy & Security on the Social Web (2014)
Lecture 2: Interactions, Frameworks, Privacy & Security on the Social Web (2014)Lecture 2: Interactions, Frameworks, Privacy & Security on the Social Web (2014)
Lecture 2: Interactions, Frameworks, Privacy & Security on the Social Web (2014)
 
How Social Software Supports Cooperative Practices in a Globally Distributed ...
How Social Software Supports Cooperative Practices in a Globally Distributed ...How Social Software Supports Cooperative Practices in a Globally Distributed ...
How Social Software Supports Cooperative Practices in a Globally Distributed ...
 

Similar to The Elusive Nature of Software Documentation

Knowledge Management ESCP EAP
Knowledge Management ESCP EAPKnowledge Management ESCP EAP
Knowledge Management ESCP EAPLukas Ritzel
 
Data fluency for the 21st century
Data fluency for the 21st centuryData fluency for the 21st century
Data fluency for the 21st centuryMartinFrigaard
 
AAEEBL Presentation 2014
AAEEBL Presentation 2014AAEEBL Presentation 2014
AAEEBL Presentation 2014Amanda Licastro
 
Cimeon Ellerton and Alison Whitaker, The Audience Agency: The Reverential Gap
Cimeon Ellerton and Alison Whitaker, The Audience Agency: The Reverential GapCimeon Ellerton and Alison Whitaker, The Audience Agency: The Reverential Gap
Cimeon Ellerton and Alison Whitaker, The Audience Agency: The Reverential GapBethBate
 
Shifting Scientific Practice - ORCID 2015
Shifting Scientific Practice - ORCID 2015Shifting Scientific Practice - ORCID 2015
Shifting Scientific Practice - ORCID 2015Kaitlin Thaney
 
Shifting Scientific Practice (K. Thaney)
Shifting Scientific Practice (K. Thaney)Shifting Scientific Practice (K. Thaney)
Shifting Scientific Practice (K. Thaney)ORCID, Inc
 
AI and the Researcher: ChatGPT and DALL-E in Scholarly Writing and Publishing
AI and the Researcher: ChatGPT and DALL-E in Scholarly Writing and PublishingAI and the Researcher: ChatGPT and DALL-E in Scholarly Writing and Publishing
AI and the Researcher: ChatGPT and DALL-E in Scholarly Writing and PublishingErin Owens
 
Knowledge Extraction from Social Media
Knowledge Extraction from Social MediaKnowledge Extraction from Social Media
Knowledge Extraction from Social MediaSeth Grimes
 
Efficient Use of Internet and Social Media Tools in Innovation Processes
Efficient Use of Internet and Social Media Tools in Innovation ProcessesEfficient Use of Internet and Social Media Tools in Innovation Processes
Efficient Use of Internet and Social Media Tools in Innovation ProcessesMikko Ahonen
 
The Next Generation of Online Social Media Applications in Education
The Next Generation of Online Social Media Applications in EducationThe Next Generation of Online Social Media Applications in Education
The Next Generation of Online Social Media Applications in Educationbeboac
 
Researching Social Media – Big Data and Social Media Analysis
Researching Social Media – Big Data and Social Media AnalysisResearching Social Media – Big Data and Social Media Analysis
Researching Social Media – Big Data and Social Media AnalysisFarida Vis
 
Visualization for Software Analytics
Visualization for Software AnalyticsVisualization for Software Analytics
Visualization for Software AnalyticsMargaret-Anne Storey
 
20220103 jim spohrer hicss v9
20220103 jim spohrer hicss v920220103 jim spohrer hicss v9
20220103 jim spohrer hicss v9ISSIP
 
Social computing: taking the long view
Social computing: taking the long viewSocial computing: taking the long view
Social computing: taking the long viewosimod
 
Technology for liberal education: the state of the art
Technology for liberal education: the state of the artTechnology for liberal education: the state of the art
Technology for liberal education: the state of the artBryan Alexander
 

Similar to The Elusive Nature of Software Documentation (20)

Knowledge Management ESCP EAP
Knowledge Management ESCP EAPKnowledge Management ESCP EAP
Knowledge Management ESCP EAP
 
Methods and Tools for Facilitating Social Participation
Methods and Tools for Facilitating Social ParticipationMethods and Tools for Facilitating Social Participation
Methods and Tools for Facilitating Social Participation
 
Community as an Asset
Community as an AssetCommunity as an Asset
Community as an Asset
 
Data fluency for the 21st century
Data fluency for the 21st centuryData fluency for the 21st century
Data fluency for the 21st century
 
AAEEBL Presentation 2014
AAEEBL Presentation 2014AAEEBL Presentation 2014
AAEEBL Presentation 2014
 
Cimeon Ellerton and Alison Whitaker, The Audience Agency: The Reverential Gap
Cimeon Ellerton and Alison Whitaker, The Audience Agency: The Reverential GapCimeon Ellerton and Alison Whitaker, The Audience Agency: The Reverential Gap
Cimeon Ellerton and Alison Whitaker, The Audience Agency: The Reverential Gap
 
Shifting Scientific Practice - ORCID 2015
Shifting Scientific Practice - ORCID 2015Shifting Scientific Practice - ORCID 2015
Shifting Scientific Practice - ORCID 2015
 
Shifting Scientific Practice (K. Thaney)
Shifting Scientific Practice (K. Thaney)Shifting Scientific Practice (K. Thaney)
Shifting Scientific Practice (K. Thaney)
 
AI and the Researcher: ChatGPT and DALL-E in Scholarly Writing and Publishing
AI and the Researcher: ChatGPT and DALL-E in Scholarly Writing and PublishingAI and the Researcher: ChatGPT and DALL-E in Scholarly Writing and Publishing
AI and the Researcher: ChatGPT and DALL-E in Scholarly Writing and Publishing
 
Knowledge Extraction from Social Media
Knowledge Extraction from Social MediaKnowledge Extraction from Social Media
Knowledge Extraction from Social Media
 
Efficient Use of Internet and Social Media Tools in Innovation Processes
Efficient Use of Internet and Social Media Tools in Innovation ProcessesEfficient Use of Internet and Social Media Tools in Innovation Processes
Efficient Use of Internet and Social Media Tools in Innovation Processes
 
The Next Generation of Online Social Media Applications in Education
The Next Generation of Online Social Media Applications in EducationThe Next Generation of Online Social Media Applications in Education
The Next Generation of Online Social Media Applications in Education
 
Researching Social Media – Big Data and Social Media Analysis
Researching Social Media – Big Data and Social Media AnalysisResearching Social Media – Big Data and Social Media Analysis
Researching Social Media – Big Data and Social Media Analysis
 
Visualization for Software Analytics
Visualization for Software AnalyticsVisualization for Software Analytics
Visualization for Software Analytics
 
20220103 jim spohrer hicss v9
20220103 jim spohrer hicss v920220103 jim spohrer hicss v9
20220103 jim spohrer hicss v9
 
Social computing: taking the long view
Social computing: taking the long viewSocial computing: taking the long view
Social computing: taking the long view
 
Technology for liberal education: the state of the art
Technology for liberal education: the state of the artTechnology for liberal education: the state of the art
Technology for liberal education: the state of the art
 
Digital Humanities Workshop
Digital Humanities WorkshopDigital Humanities Workshop
Digital Humanities Workshop
 
Dccsmf oct11-mh
Dccsmf oct11-mhDccsmf oct11-mh
Dccsmf oct11-mh
 
Building Digital Communities
Building Digital CommunitiesBuilding Digital Communities
Building Digital Communities
 

More from Margaret-Anne Storey

An Actionable Framework for Understanding and Improving Developer Experience
An Actionable Framework for Understanding and Improving Developer ExperienceAn Actionable Framework for Understanding and Improving Developer Experience
An Actionable Framework for Understanding and Improving Developer ExperienceMargaret-Anne Storey
 
ASE Keynote 2022: From Automation to Empowering Software Developers
ASE Keynote 2022: From Automation to Empowering Software Developers ASE Keynote 2022: From Automation to Empowering Software Developers
ASE Keynote 2022: From Automation to Empowering Software Developers Margaret-Anne Storey
 
Software Bots as Superheroes in the SPACE of Developer Productivity
Software Bots as Superheroes in the SPACE of Developer ProductivitySoftware Bots as Superheroes in the SPACE of Developer Productivity
Software Bots as Superheroes in the SPACE of Developer ProductivityMargaret-Anne Storey
 
What does productivity mean to developers
What does productivity mean to developersWhat does productivity mean to developers
What does productivity mean to developersMargaret-Anne Storey
 
After the Pandemic: Rethinking Developer Productivity (There’s more to it th...
After the Pandemic:  Rethinking Developer Productivity (There’s more to it th...After the Pandemic:  Rethinking Developer Productivity (There’s more to it th...
After the Pandemic: Rethinking Developer Productivity (There’s more to it th...Margaret-Anne Storey
 
Towards a Theory of Developer Satisfaction and Productivity
Towards a Theory of Developer Satisfaction and ProductivityTowards a Theory of Developer Satisfaction and Productivity
Towards a Theory of Developer Satisfaction and ProductivityMargaret-Anne Storey
 
Publish or Perish: Questioning the Impact of Our Research on the Software Dev...
Publish or Perish: Questioning the Impact of Our Research on the Software Dev...Publish or Perish: Questioning the Impact of Our Research on the Software Dev...
Publish or Perish: Questioning the Impact of Our Research on the Software Dev...Margaret-Anne Storey
 
Using a Visual Abstract as a Lens for Communicating and Promoting Design Scie...
Using a Visual Abstract as a Lens for Communicating and Promoting Design Scie...Using a Visual Abstract as a Lens for Communicating and Promoting Design Scie...
Using a Visual Abstract as a Lens for Communicating and Promoting Design Scie...Margaret-Anne Storey
 
Cascon 2016 Keynote: Disrupting Developer Productivity One Bot at a Time
Cascon 2016 Keynote: Disrupting Developer Productivity One Bot at a TimeCascon 2016 Keynote: Disrupting Developer Productivity One Bot at a Time
Cascon 2016 Keynote: Disrupting Developer Productivity One Bot at a TimeMargaret-Anne Storey
 
To Bot or Not: How Bots can Support Collaboration in Software Engineering (I...
To Bot or Not:  How Bots can Support Collaboration in Software Engineering (I...To Bot or Not:  How Bots can Support Collaboration in Software Engineering (I...
To Bot or Not: How Bots can Support Collaboration in Software Engineering (I...Margaret-Anne Storey
 
Lies, Damned Lies and Software Analytics: Why Big Data Needs Rich Data
Lies, Damned Lies and Software Analytics:  Why Big Data Needs Rich DataLies, Damned Lies and Software Analytics:  Why Big Data Needs Rich Data
Lies, Damned Lies and Software Analytics: Why Big Data Needs Rich DataMargaret-Anne Storey
 
How Developers Stay Current Using Twitter
How Developers Stay Current Using TwitterHow Developers Stay Current Using Twitter
How Developers Stay Current Using TwitterMargaret-Anne Storey
 
Benevol 2012 Keynote: The Social Software (R)evolution
Benevol 2012 Keynote: The Social Software (R)evolutionBenevol 2012 Keynote: The Social Software (R)evolution
Benevol 2012 Keynote: The Social Software (R)evolutionMargaret-Anne Storey
 
SLE 2012 Keynote: Cognitive and Social Challenges of Ontology Use in the Biom...
SLE 2012 Keynote: Cognitive and Social Challenges of Ontology Use in the Biom...SLE 2012 Keynote: Cognitive and Social Challenges of Ontology Use in the Biom...
SLE 2012 Keynote: Cognitive and Social Challenges of Ontology Use in the Biom...Margaret-Anne Storey
 
ICSE 2011: Research industry panel
ICSE 2011: Research industry panelICSE 2011: Research industry panel
ICSE 2011: Research industry panelMargaret-Anne Storey
 

More from Margaret-Anne Storey (18)

An Actionable Framework for Understanding and Improving Developer Experience
An Actionable Framework for Understanding and Improving Developer ExperienceAn Actionable Framework for Understanding and Improving Developer Experience
An Actionable Framework for Understanding and Improving Developer Experience
 
ASE Keynote 2022: From Automation to Empowering Software Developers
ASE Keynote 2022: From Automation to Empowering Software Developers ASE Keynote 2022: From Automation to Empowering Software Developers
ASE Keynote 2022: From Automation to Empowering Software Developers
 
Software Bots as Superheroes in the SPACE of Developer Productivity
Software Bots as Superheroes in the SPACE of Developer ProductivitySoftware Bots as Superheroes in the SPACE of Developer Productivity
Software Bots as Superheroes in the SPACE of Developer Productivity
 
What does productivity mean to developers
What does productivity mean to developersWhat does productivity mean to developers
What does productivity mean to developers
 
After the Pandemic: Rethinking Developer Productivity (There’s more to it th...
After the Pandemic:  Rethinking Developer Productivity (There’s more to it th...After the Pandemic:  Rethinking Developer Productivity (There’s more to it th...
After the Pandemic: Rethinking Developer Productivity (There’s more to it th...
 
Icse 2020 bof reviewing papers
Icse 2020 bof reviewing papersIcse 2020 bof reviewing papers
Icse 2020 bof reviewing papers
 
Towards a Theory of Developer Satisfaction and Productivity
Towards a Theory of Developer Satisfaction and ProductivityTowards a Theory of Developer Satisfaction and Productivity
Towards a Theory of Developer Satisfaction and Productivity
 
Publish or Perish: Questioning the Impact of Our Research on the Software Dev...
Publish or Perish: Questioning the Impact of Our Research on the Software Dev...Publish or Perish: Questioning the Impact of Our Research on the Software Dev...
Publish or Perish: Questioning the Impact of Our Research on the Software Dev...
 
Using a Visual Abstract as a Lens for Communicating and Promoting Design Scie...
Using a Visual Abstract as a Lens for Communicating and Promoting Design Scie...Using a Visual Abstract as a Lens for Communicating and Promoting Design Scie...
Using a Visual Abstract as a Lens for Communicating and Promoting Design Scie...
 
Cascon 2016 Keynote: Disrupting Developer Productivity One Bot at a Time
Cascon 2016 Keynote: Disrupting Developer Productivity One Bot at a TimeCascon 2016 Keynote: Disrupting Developer Productivity One Bot at a Time
Cascon 2016 Keynote: Disrupting Developer Productivity One Bot at a Time
 
To Bot or Not: How Bots can Support Collaboration in Software Engineering (I...
To Bot or Not:  How Bots can Support Collaboration in Software Engineering (I...To Bot or Not:  How Bots can Support Collaboration in Software Engineering (I...
To Bot or Not: How Bots can Support Collaboration in Software Engineering (I...
 
Lies, Damned Lies and Software Analytics: Why Big Data Needs Rich Data
Lies, Damned Lies and Software Analytics:  Why Big Data Needs Rich DataLies, Damned Lies and Software Analytics:  Why Big Data Needs Rich Data
Lies, Damned Lies and Software Analytics: Why Big Data Needs Rich Data
 
How Developers Stay Current Using Twitter
How Developers Stay Current Using TwitterHow Developers Stay Current Using Twitter
How Developers Stay Current Using Twitter
 
Benevol 2012 Keynote: The Social Software (R)evolution
Benevol 2012 Keynote: The Social Software (R)evolutionBenevol 2012 Keynote: The Social Software (R)evolution
Benevol 2012 Keynote: The Social Software (R)evolution
 
SLE 2012 Keynote: Cognitive and Social Challenges of Ontology Use in the Biom...
SLE 2012 Keynote: Cognitive and Social Challenges of Ontology Use in the Biom...SLE 2012 Keynote: Cognitive and Social Challenges of Ontology Use in the Biom...
SLE 2012 Keynote: Cognitive and Social Challenges of Ontology Use in the Biom...
 
Research industry panel review
Research industry panel reviewResearch industry panel review
Research industry panel review
 
ICSE 2011: Research industry panel
ICSE 2011: Research industry panelICSE 2011: Research industry panel
ICSE 2011: Research industry panel
 
Icpc 2011 storey
Icpc 2011 storeyIcpc 2011 storey
Icpc 2011 storey
 

Recently uploaded

maximum subarray ppt for killing camp students
maximum subarray ppt for killing camp studentsmaximum subarray ppt for killing camp students
maximum subarray ppt for killing camp studentsssuser82c38d
 
Getting Started with Trello for Beginners.pptx
Getting Started with Trello for Beginners.pptxGetting Started with Trello for Beginners.pptx
Getting Started with Trello for Beginners.pptxmavinoikein
 
Manual de la Mezcladora SoundCraft Notepad -12Fx
Manual de la Mezcladora SoundCraft Notepad -12FxManual de la Mezcladora SoundCraft Notepad -12Fx
Manual de la Mezcladora SoundCraft Notepad -12Fxjavierdavidvelasco17
 
Enabling Enterprise-wide OT Data access with Matrikon Data Broker.pdf
Enabling Enterprise-wide OT Data access  with Matrikon Data Broker.pdfEnabling Enterprise-wide OT Data access  with Matrikon Data Broker.pdf
Enabling Enterprise-wide OT Data access with Matrikon Data Broker.pdfJohn Archer
 
Essence of Requirements Engineering: Pragmatic Insights for 2024
Essence of Requirements Engineering: Pragmatic Insights for 2024Essence of Requirements Engineering: Pragmatic Insights for 2024
Essence of Requirements Engineering: Pragmatic Insights for 2024Asher Sterkin
 
unit 1 lecture 1 - Introduction - Software Engineering Myths.pdf
unit 1 lecture 1 - Introduction - Software Engineering Myths.pdfunit 1 lecture 1 - Introduction - Software Engineering Myths.pdf
unit 1 lecture 1 - Introduction - Software Engineering Myths.pdfStephenTec
 
India's_Generative_AI_Startup_Landscape_Report_2023_Inc42 (1).pdf
India's_Generative_AI_Startup_Landscape_Report_2023_Inc42 (1).pdfIndia's_Generative_AI_Startup_Landscape_Report_2023_Inc42 (1).pdf
India's_Generative_AI_Startup_Landscape_Report_2023_Inc42 (1).pdfgranitesrijan
 
unit I lecture 5 - Software Development Life Cycle.pdf
unit I lecture 5 - Software Development Life Cycle.pdfunit I lecture 5 - Software Development Life Cycle.pdf
unit I lecture 5 - Software Development Life Cycle.pdfStephenTec
 
Steps to Build a PWA with Odoo.pdf
Steps to Build a PWA with Odoo.pdfSteps to Build a PWA with Odoo.pdf
Steps to Build a PWA with Odoo.pdfayushinwizards
 
100 TOOLS TO MEASURE AND ANALYSE YOUR DIGITAL MARKETING EFFORTS
100 TOOLS TO MEASURE AND ANALYSE YOUR DIGITAL MARKETING EFFORTS100 TOOLS TO MEASURE AND ANALYSE YOUR DIGITAL MARKETING EFFORTS
100 TOOLS TO MEASURE AND ANALYSE YOUR DIGITAL MARKETING EFFORTSi-engage
 
Sql server types of joins with example.pptx
Sql server types of joins with example.pptxSql server types of joins with example.pptx
Sql server types of joins with example.pptxsameer gaikwad
 
unit I lecture 3 - Software Process Models.pdf
unit I lecture 3 - Software Process Models.pdfunit I lecture 3 - Software Process Models.pdf
unit I lecture 3 - Software Process Models.pdfStephenTec
 
Embracing Change - The Impact of Generative AI on Strategic Portfolio Management
Embracing Change - The Impact of Generative AI on Strategic Portfolio ManagementEmbracing Change - The Impact of Generative AI on Strategic Portfolio Management
Embracing Change - The Impact of Generative AI on Strategic Portfolio ManagementOnePlan Solutions
 
Les02 Restricting and Sorting Data using SQL.ppt
Les02 Restricting and Sorting Data using SQL.pptLes02 Restricting and Sorting Data using SQL.ppt
Les02 Restricting and Sorting Data using SQL.pptDrZeeshanBhatti
 
unit I lecture 2 - Software Engineering Ethics - Software Process.pdf
unit I lecture 2 - Software Engineering Ethics - Software Process.pdfunit I lecture 2 - Software Engineering Ethics - Software Process.pdf
unit I lecture 2 - Software Engineering Ethics - Software Process.pdfStephenTec
 
Industry 4.0: Building the Unified Namespace with Confluent, HiveMQ and Spark...
Industry 4.0: Building the Unified Namespace with Confluent, HiveMQ and Spark...Industry 4.0: Building the Unified Namespace with Confluent, HiveMQ and Spark...
Industry 4.0: Building the Unified Namespace with Confluent, HiveMQ and Spark...confluent
 
AUTOKEYUNLOCKER-BRANDS-SUPPORT-STANDARD-VERSION.pdf
AUTOKEYUNLOCKER-BRANDS-SUPPORT-STANDARD-VERSION.pdfAUTOKEYUNLOCKER-BRANDS-SUPPORT-STANDARD-VERSION.pdf
AUTOKEYUNLOCKER-BRANDS-SUPPORT-STANDARD-VERSION.pdfAutokey
 
Self scaling Multi cloud nomad workloads
Self scaling Multi cloud nomad workloadsSelf scaling Multi cloud nomad workloads
Self scaling Multi cloud nomad workloadsBram Vogelaar
 
App Builder - Hierarchical Data Apps.pptx
App Builder - Hierarchical Data Apps.pptxApp Builder - Hierarchical Data Apps.pptx
App Builder - Hierarchical Data Apps.pptxPoojitha B
 

Recently uploaded (20)

maximum subarray ppt for killing camp students
maximum subarray ppt for killing camp studentsmaximum subarray ppt for killing camp students
maximum subarray ppt for killing camp students
 
Getting Started with Trello for Beginners.pptx
Getting Started with Trello for Beginners.pptxGetting Started with Trello for Beginners.pptx
Getting Started with Trello for Beginners.pptx
 
Manual de la Mezcladora SoundCraft Notepad -12Fx
Manual de la Mezcladora SoundCraft Notepad -12FxManual de la Mezcladora SoundCraft Notepad -12Fx
Manual de la Mezcladora SoundCraft Notepad -12Fx
 
Enabling Enterprise-wide OT Data access with Matrikon Data Broker.pdf
Enabling Enterprise-wide OT Data access  with Matrikon Data Broker.pdfEnabling Enterprise-wide OT Data access  with Matrikon Data Broker.pdf
Enabling Enterprise-wide OT Data access with Matrikon Data Broker.pdf
 
Essence of Requirements Engineering: Pragmatic Insights for 2024
Essence of Requirements Engineering: Pragmatic Insights for 2024Essence of Requirements Engineering: Pragmatic Insights for 2024
Essence of Requirements Engineering: Pragmatic Insights for 2024
 
unit 1 lecture 1 - Introduction - Software Engineering Myths.pdf
unit 1 lecture 1 - Introduction - Software Engineering Myths.pdfunit 1 lecture 1 - Introduction - Software Engineering Myths.pdf
unit 1 lecture 1 - Introduction - Software Engineering Myths.pdf
 
India's_Generative_AI_Startup_Landscape_Report_2023_Inc42 (1).pdf
India's_Generative_AI_Startup_Landscape_Report_2023_Inc42 (1).pdfIndia's_Generative_AI_Startup_Landscape_Report_2023_Inc42 (1).pdf
India's_Generative_AI_Startup_Landscape_Report_2023_Inc42 (1).pdf
 
unit I lecture 5 - Software Development Life Cycle.pdf
unit I lecture 5 - Software Development Life Cycle.pdfunit I lecture 5 - Software Development Life Cycle.pdf
unit I lecture 5 - Software Development Life Cycle.pdf
 
Steps to Build a PWA with Odoo.pdf
Steps to Build a PWA with Odoo.pdfSteps to Build a PWA with Odoo.pdf
Steps to Build a PWA with Odoo.pdf
 
100 TOOLS TO MEASURE AND ANALYSE YOUR DIGITAL MARKETING EFFORTS
100 TOOLS TO MEASURE AND ANALYSE YOUR DIGITAL MARKETING EFFORTS100 TOOLS TO MEASURE AND ANALYSE YOUR DIGITAL MARKETING EFFORTS
100 TOOLS TO MEASURE AND ANALYSE YOUR DIGITAL MARKETING EFFORTS
 
Sql server types of joins with example.pptx
Sql server types of joins with example.pptxSql server types of joins with example.pptx
Sql server types of joins with example.pptx
 
unit I lecture 3 - Software Process Models.pdf
unit I lecture 3 - Software Process Models.pdfunit I lecture 3 - Software Process Models.pdf
unit I lecture 3 - Software Process Models.pdf
 
Embracing Change - The Impact of Generative AI on Strategic Portfolio Management
Embracing Change - The Impact of Generative AI on Strategic Portfolio ManagementEmbracing Change - The Impact of Generative AI on Strategic Portfolio Management
Embracing Change - The Impact of Generative AI on Strategic Portfolio Management
 
Features of IETM Software -Code and Pixels
Features of IETM Software -Code and PixelsFeatures of IETM Software -Code and Pixels
Features of IETM Software -Code and Pixels
 
Les02 Restricting and Sorting Data using SQL.ppt
Les02 Restricting and Sorting Data using SQL.pptLes02 Restricting and Sorting Data using SQL.ppt
Les02 Restricting and Sorting Data using SQL.ppt
 
unit I lecture 2 - Software Engineering Ethics - Software Process.pdf
unit I lecture 2 - Software Engineering Ethics - Software Process.pdfunit I lecture 2 - Software Engineering Ethics - Software Process.pdf
unit I lecture 2 - Software Engineering Ethics - Software Process.pdf
 
Industry 4.0: Building the Unified Namespace with Confluent, HiveMQ and Spark...
Industry 4.0: Building the Unified Namespace with Confluent, HiveMQ and Spark...Industry 4.0: Building the Unified Namespace with Confluent, HiveMQ and Spark...
Industry 4.0: Building the Unified Namespace with Confluent, HiveMQ and Spark...
 
AUTOKEYUNLOCKER-BRANDS-SUPPORT-STANDARD-VERSION.pdf
AUTOKEYUNLOCKER-BRANDS-SUPPORT-STANDARD-VERSION.pdfAUTOKEYUNLOCKER-BRANDS-SUPPORT-STANDARD-VERSION.pdf
AUTOKEYUNLOCKER-BRANDS-SUPPORT-STANDARD-VERSION.pdf
 
Self scaling Multi cloud nomad workloads
Self scaling Multi cloud nomad workloadsSelf scaling Multi cloud nomad workloads
Self scaling Multi cloud nomad workloads
 
App Builder - Hierarchical Data Apps.pptx
App Builder - Hierarchical Data Apps.pptxApp Builder - Hierarchical Data Apps.pptx
App Builder - Hierarchical Data Apps.pptx
 

The Elusive Nature of Software Documentation

  • 1. The Elusive Nature of Software Documentation And Why Understanding How Knowledge Flows Matters Margaret-Anne Storey @margaretstorey
  • 3. “I, Pencil”, An essay by Leonard Read, 1958 “Simple? Yet, not a single person on the face of this earth knows how to make me” “At some point, human intelligence became collective and cumulative in a way that happened to no other animal” ― Matt Ridley, The Rational Optimist
  • 4. The role of knowledge in software development • Insights are more important assets than program text • Designers need to share theories of the problem and solution domain, not the design of the code • Much of these insights are “tacit” knowledge • No one person or team can understand everything about a technology "Programming as theory building”, Peter Naur, 1985.
  • 5. Itinerary... • How development knowledge flows and how it is created • Challenges faced in knowledge flow (externalization, communication, onboarding) • Goals for improving knowledge flow (documentation, creativity, learning) • Enablers (automation, culture, rewards, knowledge routes, specialization) • An idea!
  • 6. Knowledge creation model: Nonaka, Ikujiro; Takeuchi, Hirotaka (1995), The knowledge creating company: how Japanese companies create the dynamics of innovation, New York: Oxford University Press, p. 284, ISBN 978-0-19-509269-1 “We can know more than we can tell” Polanyi, 1966
  • 7. Communities of practice [Wenger] Three modes of social learning: • Engagement (talking to others, producing artifacts) • Imagination/reflection (of what is, what could be) • Alignment (of local activities with other processes) How effectively organizations engage in social learning depends on how develop social capital and their repertoire of tools and resources Wenger, Etienne. Communities of practice: Learning, meaning, and identity. Cambridge university press, 1998.
  • 8. M. Storey et al., The (R)evolution of Social Media in Software Engineering, ICSE Future of Software Engineering Track 2014. 2015 Externalized knowledge in project resources Tacit knowledge Types of developer knowledge: (Meta) Knowledge about networks Community/ shared knowledge 201020001990198019701968
  • 12. Studying the R community – why email and Stack Overflow are both needed for knowledge sharing "The best way to get the right answer on the Internet is not to ask a question, it's to post the wrong answer”, Ward Cunningham How the R community creates and curates knowledge: an extended study of stack overflow and mailing lists A Zagalsky, DM German, MA Storey, CG Teshima, G Poo-Caamaño, Empirical Software Engineering 2017, 1-34
  • 15. Documenting and sharing software knowledge using screencasts, L MacLeod, A Bergen, MA Storey Empirical Software Engineering 2017, 22 (3), 1478-1507
  • 17. Understanding knowledge flow at a large software company... (a work in progress)
  • 18. Focus group… to understand knowledge flow Communication channels used: Knowledge fragmentation! Fewer (integrated) channels? Work in progress...
  • 19. “Documentation: castor oil of programming” Weinberg 1975 “Incomplete or confusing documentation is the top pain point of programmers”, GitHub Open Source Developer Survey 2017
  • 20. Knowledge flow improvement goals: Ø Improve efficiency of externalizing knowledge Ø Ensure externalized knowledge is accurate, up to date and concise Ø Ensure externalized knowledge is easier to find Ø Design effective communication channels to support collaboration, tacit knowledge sharing, knowledge creation and innovation Ø Support social learning
  • 22. Documentation is just another software engineering challenge, we should automate it Amplify cognition during knowledge creation, curation and acquisition On Demand Developer Documentation (Robillard et al., ICSME 2017)
  • 23. Learn from failures: • Stack Overflow’s documentation effort Watch for risks: • Beware the “idiot savant” (The Master Algorithm, Domingos) • “Too big to know” but be aware of algorithm and data bias https://meta.stackoverflow.com/questions/303865/warlords-of-documentation-a-proposed-expansion-of-stack-overflow
  • 25. Value communication, not just documentation “Communication valued over documentation”, Roehm et al., ICSE 2012
  • 28. Need for media literacy skills (http://rheingold.com/): • Infotention • “Crap” detection • Participation • Collaboration • Network cultivation “Information is cumulative and additive, whereas truth is exclusive and selective”, Byung-Chul Han
  • 29. Documentation that is used should be counted and rewarded Unnecessary documentation efforts should be discouraged Extrinsic “rewards” already exist in some tools (e.g., Stack Overflow) but may bring unwanted side effects Tacit knowledge and intellectual work (helping others) may bring intrinsic rewards given the right culture... Reward knowledge sharing
  • 32. Map and understand how knowledge flows • Know how knowledge is created • Understand how knowledge flows • Identify blockages • Understand who the influencers are
  • 33. Gendreau, Olivier, and Pierre N. Robillard. "Knowledge acquisition activity in software development." Advances in Information Systems and Technologies. Springer, Berlin, Heidelberg, 2013. 1-10.
  • 34. "Could removal of project- level knowledge flow obstacles contribute to software process improvement? A study of software engineer perceptions." S. Mitchell and C.Seaman, Information and Software Technology 72 (2016): 151-170.
  • 36. Nurture developer knowledge trade routes • When designing communication covenants, consider channel affordances • Innovate new knowledge routes and connect existing routes
  • 41. Hub and Spoke Model, by Calefato and Lanubile http://collab.di.uniba.it/fabio/wp-content/uploads/sites/5/2014/05/icgse16-camera-ready.pdf
  • 42. Aim for high collective intelligence • Specialization drives high collective intelligence • Contributions drive high collective intelligence
  • 43. High collective intelligence enhances creativity
  • 44. Our itinerary... we are almost there • How knowledge flows and how knowledge is created in software development and why it matters • Challenges faced in knowledge creation (externalization, communication) • Goals for improving knowledge flow (documentation, creativity) • Enablers (automation, culture, rewards, knowledge routes, specialization) • An idea!
  • 45. The idea: Use automation to amplify social communication and team cognition Automation can link externalized knowledge but humans create “new” knowledge
  • 46. What is a bot? A bot is an application that performs automated, repetitive, pre-defined tasks From setting an alarm, to telling you today’s weather forecast, to gathering information Conduit between users and services through a conversational UI
  • 49. Other data driven bots for amplifying team knowledge and collaboration: Obie, Guru, Niles....
  • 50. Can we do even better? Given more insights on how developers collaborate and communicate... Given more insights on impact of knowledge routes, blockages, influencers... Given more insights from startups and successful open/closed source projects...
  • 51. • Can bots steer developers towards the right channels (e.g., Tbot) • Can a bot connect the right people (e.g., WhoBot) • Could we use a bot to detect when colleagues go astray? • Can bots help at the community level (not just for teams)? • Can bots help us balance documentation and communication? Delivery of “on demand documentation” into the middle of a conversation with feedback loops to improve and evaluate the documentation and communication If we do all of this, would documentation becomes less elusive? Expert human(s) + (simple) computer + good process will beat many expert machines (today)
  • 52. No one developer or team can understand everything How knowledge flows impacts developer productivity and innovation Knowledge externalization and communication are intertwined Nurture knowledge flow, understand how it is rewarded or blocked Automate to amplify cognition and social communication, keep the human in the loop and understand impact of automation Borrow theories from other domains (e.g., reciprocity motivation theory), and apply our data analysis tools to this data! Together tool builders and empirical researchers can make significant impact on this topic Some souvenirs... @margaretstorey mstorey@uvic.ca
  • 53. Thank you! Talk title generator and collaborator – Per Runeson, Lund Developer knowledge expert – Alexey Zagalsky “Crazy bot lady” – Carly Lebeuf Gamification and visualization expert – Matthieu Foucault Crap detector – Cassie Petrachenko My husband (Brian) and the motorbike mechanic in Powell River for fixing the leak in our boat!
  • 54. Related work • M. Storey, L. Singer, F. Figueira Filho, A. Zagalsky, and D. German, How Social and Communication Channels Shape and Challenge a Participatory Culture in Software Development, Transactions on Software Engineering 2017.
  • 55. Greetings, The 2017 IEEE Computer Society (CS) Annual Election is open until Sep 25, 2017. I was nominated for IEEE CS 2018 President-Elect and 2019 President. I kindly ask for your vote in this election. If you are an IEEE CS member, you should have received a couple of messages from IEEE CS inviting you to vote. Note that there is also an IEEE election in progress. To be eligible to vote, one must be an IEEE CS member as of June 30, 2016. Please encourage your colleagues and graduate students to vote. IEEE CS voting: goo.gl/TQDu21 My election website: goo.gl/fqMPYE My town hall slides: goo.gl/UEWUSj Over 80 recommendations: goo.gl/w71JPM Please vote now. If you already voted, thank you very much. Thank you very much for your support. Best wishes, Hausi Müller