Segredos do Windows: Como explicar seus recursos com eficiência
Se você não pode explicar sua característica sem usar chavões, então não espere que alguém para entendê-lo.
Raymond Chen
Uma das coisas que você tem que lembrar ao escrever documentação para o consumo externo é que a pessoa está lendo a documentação porque eles não sabem tudo o que você sabe. Quando você está tentando explicar o seu recurso para alguém, você precisa parar e tirar seus óculos cor característica.
Após todos estes anos, eu ainda não tinha idéia que era o Windows CardSpace. Em uma discussão sobre Windows Live ID (como era então conhecido), alguém respondeu a uma pergunta, citando uma seção de uma página Web, intitulada "Como faz Windows Live ID participar em the Identidade Metasystem e trabalho com InfoCard":
"A Microsoft está trabalhando com os outros na indústria para criar um meta-sistema de identidade que traz existentes e futuros provedores de identidade em um ecossistema de identidade conectados e permite que os usuários finais para controlar a utilização de suas identidades. O serviço Windows Live ID participará o metasystem de identidade como provedor de um identidade entre muitos, capaz de aceitar pedidos de outros provedores de identidade e transformá-los para que eles podem ser usados no Microsoft online services."
Aqui está o que esse parágrafo parecia-me:
"A Microsoft está trabalhando com os outros na indústria para criar um chavão que traz chavões existentes e futuras em um chavão e usuários de chavões para palavra-chave. O serviço Windows Live ID participará o chavão como um chavão entre muitos, capaz de chavão e chavão-los para que eles possam chavão."
Nesse ponto, parei a leitura e perguntou se alguém era capaz de traduzir esse parágrafo em inglês. Ninguém poderia, mas algumas pessoas em particular me disseram, "Eu pensei a mesma coisa, mas era muito medo de dizer qualquer coisa."
Todas as minhas tentativas de aprender sobre CardSpace levaram nada. Quem escreveu a CardSpace documentação assume-se que o consumidor já estava familiarizado com o CardSpace. Eles alegremente explicaram que o CardSpace gerenciado cartões, que era a unidade de identidade baseada em declarações. Em outras palavras: "O CardSpace gerencia chavões, que são a unidade de palavra-chave palavra-chave." Eu desisti de ler a documentação naquele momento.
Aqui está outro exemplo de uma das minhas tentativas fracassadas para descobrir a natureza ilusória do CardSpace:
Uma demonstração realizada pelo gerente de projeto CardSpace começou com uma seção sobre "O que o usuário final vai experimentar." Isso foi ótimo, porque eu podia ver o que significava para mim — o cara que não tinha idéia que CardSpace é suposto para ser ou como ele funciona.
Essa demonstração consistia em uma página da Web que disse, "Clique no botão abaixo para enviar um cartão."
OK, o demo já havia perdido me da seu muito primeiro screenshot.
"O que é um cartão?" Perguntei-me. "É esta me pedindo meu cartão de crédito?"
Eu alimentado por meio de qualquer maneira. O demo clicado o botão, e uma nova caixa de diálogo apareceu. "Aqui, você pode ver que eu tenho uma seleção de cartões disponíveis."
Ele ainda não tinha me disse foi que um cartão. De onde vêm os cartões? Por que eles são úteis? Eles vêm a fada de cartão do CardSpace?
Eu furei com o demo, no entanto. A demonstração selecionado um cartão e, em seguida, mostrou um monte de XML na tela.
Que foi o UX? Cliquei em um botão, eu não entendia e mostrou-se um diálogo repleto de feijões mágicos. Então eu selecionei dentre os feijões mágicos, e algum XML apareceu na tela?
Eu fui para a ajuda online do CardSpace. Eu percebi, "Esta é a documentação escrita especificamente para usuários não-técnicos. Com certeza isso vai me explicar todo o ponto dessa coisa de CardSpace."
Bem, pelo menos que a documentação foi um pouquinho melhor. A ajuda on-line me disse que o CardSpace é "um sistema para a criação de relacionamentos com Web sites e serviços."
Isso não soar como qualquer coisa que eu queria. Eu não queria um relacionamento com um site da Web. Eu só queria visitar CNN e ler o dia top de notícias.
Nesse ponto, eu desisti totalmente. Percebi que uma coisa é se seu gerência superior não pode explicar seu projeto. Outra coisa é inteiramente quando você mesmo não consegue explicar a natureza de seu próprio projeto.
Para ser justo, a equipe do CardSpace foi criada pelo seu ambiente. O produto foi concebido para e viveu no mundo da identidade digital. Uma propriedade comum do mundo identidade digital é que ninguém ali é capaz de descrever o que eles fazem sem recorrer a chavões. Quanto mais tempo você gastar tempo em um mundo onde todo mundo fala de certa forma, quanto mais você assumir que todo mundo fala dessa maneira — mesmo se é só o povo na sua pequena camarilha que falam dessa forma.
Você deve ter a consciência de si para perceber que você está cometendo esse erro e colocar-se na pele de alguém que não passou os últimos anos falando o jargão peculiar de seu campo. Somente quando você preencher a lacuna entre os insiders e os outsiders você pode dizer que você já conseguiu se comunicar.
.jpg)
Raymond Chendo Web site, The Old New Thing e identicamente intitulado livro (Addison-Wesley, 2007) tratam Windows histórico, programação Win32 e riscos de segurança que a irritantes arquivos MIDI.