ThoughtWorks
  • Kontakt
  • Español
  • Português
  • English
  • 中文
Übersicht
  • Delivery Mindset trifft Software-Exzellenz

    Verfolgen Sie einen innovativen Ansatz in der Softwareentwicklung, um noch schneller erfolgreich zu sein.

    Erkenntnisgestützte Entscheidungsfindung

    Nutzen Sie Ihre Datenbestände, um neue Geschäftsmöglichkeiten zu erschließen.

  • Betriebsmodelle ohne Reibungsverluste

    Verbessern Sie die Fähigkeit Ihres Unternehmens, auf Veränderungen zu reagieren.

    Plattform Strategie

    Entwicklung dynamischer Technologieplattformen, die sich an Ihre Geschäftsstrategie anpassen.

  • Experience Design und innovative Produkte

    Liefern Sie schnell außergewöhnliche Produkte und Kundenerlebnisse. Entwickeln Sie Design und Funktion kontinuierlich weiter.

    Partnerschaften

    Nutzung unseres Netzwerks aus vertrauenswürdigen Partnern, um noch bessere Ergebnisse für unsere Kunden zu erzielen.

Übersicht
  • Automobil
  • Clientech, Energie und Versorgung
  • Banken und Versicherungen
  • Gesundheit
  • Medien
  • Non-Profit
  • Öffentlicher Sektor
  • Handel und E-Commerce
  • Reise und Transport
Übersicht

Unsere Empfehlungen

  • Technologie

    Ausführliche Betrachtungen neuer Technologien.

  • Business

    Aktuelle Business-Insights, Strategien und Impulse für digitale Querdenker.

  • Kultur

    Insights zu Karrieremöglichkeiten und unsere Sicht auf soziale Gerechtigkeit und Inklusivität.

Digitale Veröffentlichungen und Tools

  • Technology Radar

    Unser Leitfaden für aktuelle Technologietrends.

  • Perspectives

    Unsere Publikation für digitale Vordenker*innen

  • Digital Fluency Model

    Ein Modell zur Priorisierung digitaler Fähigkeiten, um für das Unvorhersehbare bereit zu sein.

  • Decoder

    Der Technology-Guide für Business Entscheider

Alle Insights

  • Artikel

    Expertenwissen für Ihr Unternehmen.

  • Blogs

    Persönliche Perspektiven von ThoughtWorkern aus aller Welt.

  • Bücher

    Stöbern Sie durch unsere umfangreiche Bibliothek.

  • Podcasts

    Spannende Gespräche über das Neueste aus Business und Technologie.

Übersicht
  • Bewerbungsprozess

    Finde heraus, was dich in unserem Bewerbungsprozess erwartet.

  • Hochschulabsovent*innen und Quereinsteiger*innen

    Dein Einstieg in die IT-Welt.

  • Stellenangebote

    Finde offene Stellen in deiner Region.

  • In Kontakt bleiben

    Abonniere unsere monatlichen Updates.

Übersicht
  • Konferenzen und Events
  • Diversity und Inclusion
  • Neuigkeiten
  • Open Source
  • Management
  • Social Change
  • Español
  • Português
  • English
  • 中文
ThoughtWorksMenü
  • schließen   ✕
  • Unsere Services
  • Unsere Kunden
  • Insights
  • Karriere
  • Über uns
  • Kontakt
  • Zurück
  • schließen   ✕
  • Übersicht
  • Delivery Mindset trifft Software-Exzellenz

    Verfolgen Sie einen innovativen Ansatz in der Softwareentwicklung, um noch schneller erfolgreich zu sein.

  • Experience Design und innovative Produkte

    Liefern Sie schnell außergewöhnliche Produkte und Kundenerlebnisse. Entwickeln Sie Design und Funktion kontinuierlich weiter.

  • Betriebsmodelle ohne Reibungsverluste

    Verbessern Sie die Fähigkeit Ihres Unternehmens, auf Veränderungen zu reagieren.

  • Erkenntnisgestützte Entscheidungsfindung

    Nutzen Sie Ihre Datenbestände, um neue Geschäftsmöglichkeiten zu erschließen.

  • Partnerschaften

    Nutzung unseres Netzwerks aus vertrauenswürdigen Partnern, um noch bessere Ergebnisse für unsere Kunden zu erzielen.

  • Plattform Strategie

    Entwicklung dynamischer Technologieplattformen, die sich an Ihre Geschäftsstrategie anpassen.

  • Zurück
  • schließen   ✕
  • Übersicht
  • Automobil
  • Clientech, Energie und Versorgung
  • Banken und Versicherungen
  • Gesundheit
  • Medien
  • Non-Profit
  • Öffentlicher Sektor
  • Handel und E-Commerce
  • Reise und Transport
  • Zurück
  • schließen   ✕
  • Übersicht
  • Unsere Empfehlungen

  • Technologie

    Ausführliche Betrachtungen neuer Technologien.

  • Business

    Aktuelle Business-Insights, Strategien und Impulse für digitale Querdenker.

  • Kultur

    Insights zu Karrieremöglichkeiten und unsere Sicht auf soziale Gerechtigkeit und Inklusivität.

  • Digitale Veröffentlichungen und Tools

  • Technology Radar

    Unser Leitfaden für aktuelle Technologietrends.

  • Perspectives

    Unsere Publikation für digitale Vordenker*innen

  • Digital Fluency Model

    Ein Modell zur Priorisierung digitaler Fähigkeiten, um für das Unvorhersehbare bereit zu sein.

  • Decoder

    Der Technology-Guide für Business Entscheider

  • Alle Insights

  • Artikel

    Expertenwissen für Ihr Unternehmen.

  • Blogs

    Persönliche Perspektiven von ThoughtWorkern aus aller Welt.

  • Bücher

    Stöbern Sie durch unsere umfangreiche Bibliothek.

  • Podcasts

    Spannende Gespräche über das Neueste aus Business und Technologie.

  • Zurück
  • schließen   ✕
  • Übersicht
  • Bewerbungsprozess

    Finde heraus, was dich in unserem Bewerbungsprozess erwartet.

  • Hochschulabsovent*innen und Quereinsteiger*innen

    Dein Einstieg in die IT-Welt.

  • Stellenangebote

    Finde offene Stellen in deiner Region.

  • In Kontakt bleiben

    Abonniere unsere monatlichen Updates.

  • Zurück
  • schließen   ✕
  • Übersicht
  • Konferenzen und Events
  • Diversity und Inclusion
  • Neuigkeiten
  • Open Source
  • Management
  • Social Change
Blogs
Wählen Sie ein Thema
Alle Themen ansehenschließen
Technologie 
Agiles Projektmanagement Cloud Continuous Delivery  Data Science & Engineering Defending the Free Internet Evolutionäre Architekturen Experience Design IoT Sprachen, Tools & Frameworks Modernisierung bestehender Alt-Systeme Machine Learning & Artificial Intelligence Microservices Plattformen Sicherheit Software Testing Technologiestrategie 
Geschäft 
Financial Services Global Health Innovation Retail  Transformation 
Karriere 
Karriere Hacks Diversity und Inclusion Social Change 
Blogs

Themen

Thema auswählen
  • Technologie
    Technologie
  • Technologie Überblick
  • Agiles Projektmanagement
  • Cloud
  • Continuous Delivery
  • Data Science & Engineering
  • Defending the Free Internet
  • Evolutionäre Architekturen
  • Experience Design
  • IoT
  • Sprachen, Tools & Frameworks
  • Modernisierung bestehender Alt-Systeme
  • Machine Learning & Artificial Intelligence
  • Microservices
  • Plattformen
  • Sicherheit
  • Software Testing
  • Technologiestrategie
  • Geschäft
    Geschäft
  • Geschäft Überblick
  • Financial Services
  • Global Health
  • Innovation
  • Retail
  • Transformation
  • Karriere
    Karriere
  • Karriere Überblick
  • Karriere Hacks
  • Diversity und Inclusion
  • Social Change
TransformationGeschäft

Agile Technical Writing

Elena Yatzeck Elena Yatzeck

Published: Nov 9, 2010

IT community members catechized on the Agile Manifesto will recall that the original signers placed a higher value on "working software" than on "comprehensive documentation." But is working software in isolation our ultimate goal?  I think that as the Agile community has moved in the direction of delivering value, rather than just delivering working software, we are now newly realizing we need more than just rich face-to-face conversations at white boards.  We need accessible archives populated by well-structured documents which have been written in full sentences.  It's time to even the balance.

 

 

Scott Ambler has done the Agile community a huge service with frequent and comprehensive surveys to determine what people are actually doing in the field, and how well it's working (see this Ambysoft page for a full list of his surveys and results).  As Ambler reviewed his results in 2008, he was surprised to find that Agile projects are actually more likely, and not less likely, than their traditional counterparts to produce "comprehensive documentation" such as "user manual, operations documentations, support documentation, system overview documentation."  Ambler explains this result by saying:

So, I was thinking about this a bit; and what I think was going on is one of the things that we do know, is that Agilists are actually more likely to deliver than traditionalists. That type of documentation is something that you would write towards the end of the project as things stabilize. So, I think what’s going on is Agilists are more likely to get to the end, therefore, they are more likely to do the type of work that you would do at the end, which is finish up this documentation. That’s my theory at least. I can’t back that up with real numbers but that’s what the trend appears to… (both quotations from Ambler, 2008)

One of the joys of early Agile development was its return to a mode of working which is natural for humans: small groups, close proximity, verbal communication, shared whiteboard drawing, project management through tactile movement of cards or sticky notes around on a big visual chart.  And what about actually being able to sit and talk issues through completely in one sitting rather than futilely exchanging emails in stolen moments between other meetings?  The success and happiness of these early teams is literally hard-wired into our DNA, if you believe in socio-biology, and it is intuitively beguiling to the point that today (again by Ambler's count) over 76% of American corporations are at least dabbling in Agile techniques, despite very few on-the-ground measures of what the return on investment might be.

The importance of wide-band face-to-face communication as part of the software development process is undeniable.  But I believe this heady success has led some people to confuse what is "necessary" with what is "sufficient."  As Agile teams embraced this rich and necessary form of communication, proponents began to assert that immediate, personal, and primarily verbal or visual communcations forms were better than their written alternative in most or all settings and contexts.  See for example this widely distributed chart on the "effectiveness" of communications methods.  It is completely brilliant, and worth reproducing even if I weren't quibbling with it:

 

 

 

Anyone who has done any greenfield software development at all will attest to the validity of this chart in expressing the best way to do "modeling," if that is defined as the creative and iterative process of determining what needs to be done, and how it should be done.

Anyone who has ever done production support of a legacy, or "brownfield" application of any vintage, however, will likely find some fault with the lower curve on the diagram, describing the best way to write lasting documentation.  And in fact, even greenfield developers may disagree that incorporating the visual picture is the sole predictor of either "richness" of communication or overall "effectiveness."

  • If you have a "system down" situation, do you want to bring up a video (if you can find it) and watch it through to figure out what might be going wrong?
  • How many times have you silently mouthed the words "Oh thank goodness!" or the equivalent when someone dug up an old yellowed computer printout for you that had the complete set of metadata translations typed out along with pithy descriptions of what the terms meant in context at the time the application was originally written?
  • And truthfully, how many times have you been grateful that someone took comprehensive minutes during your brainstorming meeting to put context around your architectural diagram, capture intent, and record immediate action items?  How handy was that email to you?  If you were there, do you now want to watch the whole meeting again on video, complete with incomprehensible low-volume discussions you can't hear, nose-blowing, groin-area adjustments, and long-winded tangents from people who aren't usually that annoying (or who are)?  If you weren't able to attend the meeting, how much will you get from the video?

When you introduce a time parameter into the evaluation, the graph looks a little different:

>

 

 

I don't mean to trivialize the achievement of early Agile adopters who have brought people back into the process, nor do I propose to claim that comprehensive written documentation is more important than written code.  Using what Jim Highsmith calls"And" Leadership, I'm saying that we should keep both the baby AND the bath water.

No, wait.

I mean we shouldn't throw out the use of written communication for post-facto documentation just because we want to get rid of big speculative requirements drafting.  For the long term, written communication can do some things that video can't do, and even in-person communication can't.  When you've had that really long, contentious meeting, it's extremely helpful for the consensus you've reached to be neatly summarized in words and whatever pictures are necessary.  Otherwise, you're going to have the argument again tomorrow, in two weeks, and/or next year.

Over time, the delivery of business value depends almost as much on the delivery of comprehensive documentation as it does on the delivery of working software.  Let the light saber wars begin.

This post is from Pragmatic Agilist by Elena Yatzeck. Click here to see the original post in full.

  • Unsere Services
  • Unsere Kunden
  • Insights
  • Karriere
  • Über uns
  • Kontakt

WeChat

×
QR code to ThoughtWorks China WeChat subscription account

Presseanfragen | Datenschutz | Impressum | Modern Slavery statement ThoughtWorks| Barrierefreies Webdesign | © 2021 ThoughtWorks, Inc.