Windows Confidential: Vermeiden Sie Jargon
Wenn Sie Ihre Funktion ohne Verwendung von Schlagworten nicht erklären können, dann erwarten Sie nicht jemand, Sie zu verstehen.
Raymond Chen
Eines der Dinge, die Sie haben, daran zu erinnern, beim Schreiben von Dokumentation für externe Verbrauch ist, dass die Person Ihre Dokumentation liest, weil sie nicht alles wissen, wissen Sie. Wenn Sie versuchen, Ihre Funktion, jemand zu erklären, müssen Sie stoppen und nehmen Ihre Funktion gefärbte Brille.
Nach all den Jahren hatte ich noch keine Ahnung was war Windows CardSpace. In einer Diskussion über Windows Live ID (wie es damals genannt wurde), jemand beantwortet eine Frage mit einem Zitat aus einem Abschnitt einer Web-Seite mit dem Titel "Wie Windows Live teilnehmen in der Identitätsmetasystem und arbeiten mit InfoCard ID":
"Microsoft arbeitet mit anderen in der Branche ein Identitätsmetasystem erstellen, bestehende und künftige Identitätsprovider in ein Ökosystem des angeschlossenen Identität bringt und ermöglicht Endbenutzern, die Verwendung ihrer Identitäten. Der Windows Live ID-Dienst teilnehmen im Identitätsmetasystem als eine Identitätsanbieter unter vielen, in der Lage, Ansprüche von anderen Anbietern Identität anzuerkennen und sie zu transformieren, so dass sie innerhalb von Microsoft online Services verwendet werden können."
Hier ist, was mir dieser Absatz wie Klang:
"Microsoft arbeitet mit anderen in der Branche ein Schlagwort zu erstellen, die bestehende und künftige Schlagwörtern in ein Modewort und Modeworte Benutzer zum Schlagwort bringt. Der Windows Live ID-Dienst nehmen das Schlagwort als ein Modewort unter vielen, Stichwort und Schlagwort können sie an so dass sie Modewort."
An diesem Punkt, ich hörte lesen und fragte, ob jemand in der Lage, dass Absatz ins Englische zu übersetzen. Niemand konnte, aber ein paar Leute privat sagte mir, "Ich dachte das gleiche, aber hatte auch Angst, etwas zu sagen."
Alle meine Versuche, über CardSpace lernen geführt nirgendwo. Die Menschen, die die CardSpace-Dokumentation schrieb davon ausgegangen, dass der Verbraucher bereits mit CardSpace vertraut war. Sie erklärten fröhlich, dass CardSpace Karten, verwaltet die war die Einheit anspruchsbasierter Identität. Mit anderen Worten: "CardSpace verwaltet Schlagworte, die die Einheit des Schlagwort Schlagwort bilden." Ich lesen die Dokumentation zu diesem Zeitpunkt aufgegeben.
Hier ist ein weiteres Beispiel eines meiner gescheiterten versuchen, herauszufinden, die schwer fassbare Natur des CardSpace:
Eine Demo, die unter der Leitung von der CardSpace-Projektmanager begann mit einem Abschnitt auf "Was wird der Endbenutzer erleben." Das war toll, weil ich sehen konnte, was es für mich bedeutete — der Kerl, der keine Ahnung hatte, was CardSpace werden soll oder wie es funktioniert.
Diese Demo bestand aus einer Webseite, die sagte: "auf die Schaltfläche unten, um eine Karte zu senden" klicken.
OK — die Demo bereits verlor mich aus seinen allerersten Screenshot.
"Was ist eine Karte?" Ich wunderte mich. "Ist diese Fragen mich für meine Kreditkarte?"
Ich angetrieben durch sowieso. Die Demo geklickt und ein neues Dialogfeld aufgetaucht. "Hier, sehen Sie, dass ich eine Auswahl an Karten zur Verfügung haben."
Es hatte nicht mir noch erzählt, was für eine Karte war. Woher kommen die Karten? Warum sind sie nützlich? Kommen sie die CardSpace-Karte-Fee?
Ich blieb trotzdem mit der Demo. Die Demonstration eine Karte ausgewählt und dann eine Reihe von XML auf dem Bildschirm zeigte.
War das die UX? Ich klickte ich verstand nicht und zeigte einen Dialog mit magische Bohnen gefüllt. Dann wählte ich eine magische Bohnen, und zeigte einige XML sich auf dem Bildschirm?
Ich ging zu der online-Hilfe für CardSpace. Ich dachte, "Dies ist die Dokumentation, speziell geschrieben für technisch nicht versierte Nutzer. Sicherlich werde mir den springende Punkt bei dieser CardSpace-Sache erklären."
Nun, zumindest, dass Dokumentation ein kleines bisschen besser war. Der online-Hilfe sagte mir, dass CardSpace "ein System zum Erstellen von Beziehungen mit Webseiten und Dienste."
Klang nicht, die wie alles, was ich wollte. Ich wollte nicht, eine Beziehung mit einer Website. Ich wollte nur CNN zu besuchen und Lesen des Tages top Geschichten.
Zu diesem Zeitpunkt gab ich völlig. Ich erkannte, dass es eine Sache ist, wenn Ihre oberen Management kann nicht erklären, Ihr Projekt. Es ist etwas anderes, völlig, wenn Sie selbst Ihr eigenes Projekt nicht erklären können.
Um fair zu sein, wurde das CardSpace-Team von ihrer Umgebung eingerichtet. Das Produkt wurde entwickelt für und lebte in der Welt der digitalen Identität. Ein Allgemeingut der digitalen Identität-Welt ist, dass niemand es in der Lage ist zu beschreiben, was sie tun, ohne Rückgriff auf Modewörter. Je länger Sie verbringen Zeit in einer Welt, wo jeder eine bestimmte Weise spricht, je mehr Sie gehen davon aus, dass jeder so spricht — auch wenn es nur die Menschen in Ihrem kleinen Clique, die auf diese Weise zu sprechen.
Sie haben das Selbstbewusstsein zu erkennen, dass Sie diesen Fehler machst, und versetzen Sie sich in die Schuhe von jemandem, der nicht der letzten Jahre sprechen des Feldes eigentümlichen Fachsprache verbracht hat. Nur dann, wenn Sie die Lücke zwischen Insider und Outsider kann man sagen, dass Sie in der Kommunikation erfolgreich habe.
.jpg)
Raymond Chenidentisch mit dem Titel Buch (Addison-Wesley, 2007) und des Web-Site, The Old New Thing, befassen sich mit der Geschichte von Windows, Win32-Programmierung und Security-Risiken durch lästige MIDI-Dateien.