Texto de interface do usuário e Ajuda para Visual Studio

Texto e terminologia da interface do usuário

Um texto compreensível é crucial para uma interface do usuário eficaz. Os usuários de software tendem a ler os rótulos primeiro, ou seja, aqueles mais relevantes para concluir a tarefa em questão. O texto estático é lido com menos frequência. Planeje que os usuários iniciem suas sessões de trabalho com uma varredura rápida de toda a janela, seguida por uma leitura da interface do usuário nesta ordem aproximada:

1. Controles interativos no centro

2. Botões de confirmação

3. Controles interativos encontrados em outro lugar

4. Instruções principais

5. Explicações complementares

6. Window title

7. Outro texto estático no corpo principal

Padrões de uso para texto da interface do usuário

Texto da barra de título

O texto da barra de título deve corresponder ao comando que gerou a interface do usuário.

Texto instrucional (texto auxiliar)

Em algumas caixas de diálogo, é útil fornecer instruções principais proeminentes para explicar o que fazer na janela ou na página. Isso às vezes é chamado de "texto auxiliar".

Regras de estilo de escrita para texto auxiliar

• Não explique o óbvio. A menos que seja absolutamente necessário, não inclua texto instrutivo.

• O texto instrucional é sempre colocado na parte superior da caixa de diálogo e deve se referir à tarefa que está sendo executada.

• Explique com precisão aos usuários o que eles precisam fazer. Evite comunicação excessiva e redundância.

• Revise cada janela e elimine palavras e instruções duplicadas.

• Mantenha o texto instrucional curto. Se mais informações forem necessárias para determinados usuários ou cenários, forneça um link para um tópico online conceitual detalhado.

• Escreva seu texto para que cada palavra tenha peso e seja necessária.

• Siga as orientações existentes da Microsoft para Texto e Estilo e Tom da Interface do Usuário.

Instruções complementares

As instruções complementares fornecem informações adicionais que ajudam o usuário a entender os controles ou agrupamentos de controle. Isso também pode incluir texto de dica necessário para entender o formato que o controle de entrada está esperando. Use instruções suplementares com moderação. Reserve-os para casos em que é provável que o usuário não entenda completamente as ramificações da escolha que está fazendo.

Texto suplementar no Visual Studio

Texto suplementar no Visual Studio

InfoDicas

Muitas vezes, o texto instrucional pode ser muito longo para ser posicionado no local na interface do usuário ou pode ser útil apenas para novos usuários, parecendo confuso para usuários experientes. Nesse caso, o texto instrucional/informativo deve ser colocado como uma dica de ferramenta em uma InfoTip.

As Dicas de Informações devem ser colocadas perto dos controles aos quais estão relacionadas e devem usar o ícone específico da Dica de Informação, que é discreto, mas perceptível.

Exemplo de uma dica de informação no Visual Studio

Escrevendo regras de estilo para InfoTips

• Escreva InfoTips como frases completas. Eles exigem verbos específicos, caso de frase e pontuação final.

• Use o InfoTips para complementar suas instruções ou informações principais. Se você está apenas usando palavras diferentes para reafirmar a ideia principal, você não precisa de uma InfoTip.

• Mantenha as InfoTips curtas e doces. Use palavras pequenas e linguagem simples e cotidiana que apoie e incentive o usuário.

• Siga as orientações existentes da Microsoft para Texto e Estilo e Tom da Interface do Usuário.

Rótulos de controle

Os rótulos de controle devem ser curtos, concisos e seguir as diretrizes da Área de Trabalho do Windows para Controles.

Para obter mais informações sobre o formato de rótulo de controle e posicionamento na interface do usuário, consulte Layout para Visual Studio.

Links de ajuda

Os links de ajuda podem ser colocados no texto instrucional ou no corpo da interface do usuário. Eles podem ser links para a Ajuda ou iniciar caixas de diálogo internas.

Regras de estilo visual para links da Ajuda

• Use as cores de ambiente corretas para hiperlinks. Um hiperlink com estilo correto não piscará brevemente em vermelho quando clicado. Se você vir isso, então é uma indicação de que as cores do ambiente não estão sendo usadas.

• Os sublinhados só devem ser usados ao passar o mouse ou quando o link estiver incorporado em um parágrafo.

• Para obter informações mais detalhadas sobre estilos visuais e de interação para hiperlinks, consulte Botões e hiperlinks.

Escrevendo regras de estilo para links da Ajuda

• Ao iniciar caixas de diálogo, mantenha os padrões de reticências: sem reticências para navegação, reticências se a tarefa exigir interface do usuário adicional.

  

  Uma reticência (...) em um link da Ajuda indica que a tarefa exigirá interface do usuário adicional.

• Os links não devem começar com "Aprender", pois essa não é a intenção do usuário. O usuário quer responder a uma pergunta específica, não receber uma educação geral.

• Links de ajuda de frase para que eles façam a pergunta que o tópico responderá.

  Incorreto: "Saiba mais sobre os preços dos Serviços Móveis do Windows Azure"

  Correto: "Quais opções de preços estão disponíveis para os Serviços Móveis do Windows Azure?"

• Nunca use Click... para o texto do link.

• Nunca vincule apenas a palavra "aqui". Isso é problemático para alguns leitores de tela, que expressarão apenas a palavra com hiperlink.

  Incorreto: "Encontre informações sobre os Serviços Móveis do Windows Azure aqui"

  Correto: "Quais opções de preços estão disponíveis para os Serviços Móveis do Windows Azure?"

• Para obter mais informações sobre o estilo de escrita correto para links da Ajuda, consulte as diretrizes da Área de Trabalho do Windows para Ajuda.

Texto da dica

O texto de dica aparece como uma marca d'água dentro de um controle ou abaixo dele. A formatação correta será aplicada usando o token VSColors apropriado, Environment.GrayText.

Ele pode aparecer de várias formas.

• No lugar da etiqueta de controle:

  

• Com um verbo, dando instruções:

  

• Com texto indicando uma entrada obrigatória:

  

Texto de marca d'água

Em uma superfície de design vazia, o texto deve indicar o que fazer, bem como fornecer links para abrir outras janelas relacionadas, se apropriado:

Exemplo de texto de marca d'água no Visual Studio

Terminologia comum

Termo	Explicação	Comentário
Entrar / Sair	Verbos usados como sinônimo da Web para representar a autenticação em uma propriedade da Web. Nos clientes, usamos isso uma vez como uma noção de nível superior para entrar e sair da conexão de usuário do IDE, que representa uma identidade de nível superior que fornece recursos de nível superior, como roaming e licenciamento, que não estão disponíveis com todas as outras conexões.	O usuário do IDE é o único recurso que deve representar um verbo de entrada/saída, pois representa o usuário do IDE de nível superior.
Conectar/Desconectar	Use em locais onde um recurso mantém uma única conexão com um serviço online.	O Gerenciador de Servidores, onde você só pode ter uma conexão ativa do Azure por vez, é um exemplo de Conectar/Desconectar.
Adicionar / Remover	Não destrutivo. Use ao adicionar ou remover algo de uma lista.	A caixa de diálogo de lista de servidores do Gerenciador de Conexões do TFS é um exemplo de Adicionar/Remover.
Excluir	Destrutivo. Use somente quando o elemento que está sendo removido for permanentemente descartado ou excluído do disco.	"Excluir" geralmente requer um prompt se o resultado for excluir um arquivo do disco.

Mensagens de erro

Erros acontecem. Definir limitações sobre o que o usuário pode fazer é um primeiro passo sensato para evitar mensagens de erro evitáveis. No entanto, quando ocorre um erro, uma mensagem de erro bem escrita pode ajudar muito a atenuar o problema. As mensagens de erro são, sem dúvida, um dos tipos mais importantes de notificação que o usuário vê, porque são síncronas e indicam um problema que precisa ser resolvido. Mensagens de erro mal escritas deixam os usuários por conta própria para decidir a causa dos erros e quaisquer soluções possíveis.

Os usuários podem parar de prestar atenção em mensagens de erro usadas em excesso ou confusas, portanto, escreva apenas as mensagens necessárias que agreguem valor à experiência do usuário. Se a mensagem for simplesmente uma notificação, use uma apresentação alternativa.

Regras para criar uma mensagem de erro

• Ao construir mensagens de erro, escolha o nível de erro apropriado para o público. Busque resumos simples que forneçam uma ação que o usuário possa tomar, se aplicável. Não indique nada que o usuário não precise saber.

• Prestar assistência construtiva. É mais fácil ler e agir em uma mensagem de erro que contém instruções.

• Não use negativos duplos.

• Execute uma verificação gramatical e ortográfica automatizada e manual em qualquer mensagem de erro que você escrever.

• Para mensagens de erro complexas, evite comunicações sequenciais. Nunca use uma conexão F1 para a mensagem de erro. A mensagem em si deve ser suficiente.

• Use o ícone correto.

• Torne as perguntas fáceis de entender e use botões que tenham opções claras, como "Excluir" e "Cancelar".

• Para advertências, seja claro sobre qual será a consequência do processo. Os botões devem indicar a consequência.

• Para erros, descreva o que o usuário pode fazer para corrigir o problema. Os botões devem ser ações ou dizer "Fechar". Não use um botão "OK" para uma mensagem de erro.

• Algumas perguntas a se fazer ao construir uma mensagem de erro:

  • O usuário pode descobrir como resolver o problema com este erro sozinho?

  • O usuário usa o mesmo vocabulário desse erro?

  • Esse erro é ambíguo ou compartilhado em várias situações? Em caso afirmativo, como orientar os usuários para a solução de que precisam?

Erros de compilação

Como o Visual Studio é uma ferramenta de desenvolvimento de software, muitos de seus componentes têm uma etapa de compilação, conversão ou codificação para converter o trabalho do desenvolvedor em forma binária. Essas conversões podem causar erros quando o compilador não pode processar arquivos criados incorretamente ou quando as opções do compilador não foram definidas corretamente.

Os usuários do Visual Studio podem gastar um grande número de horas de desenvolvimento resolvendo erros de compilação. Esse tempo de resolução aumenta quando os erros têm dependências ou quando as mensagens de erro são mal escritas, o que pode dificultar a descoberta da origem do erro.

Os melhores erros de compilação são aqueles que não ocorrem em primeiro lugar, e é por isso que o Visual Studio fornece squiggles de Preenchimento Automático e IntelliSense. Validadores de esquema e ferramentas semelhantes fornecem o mesmo tipo de feedback. Esses mecanismos orientam proativamente o usuário a construir código bem formado, diminuindo a chance de erros de compilação.

Visual Studio fornece uma janela de ferramenta onde os usuários podem ler e navegar pelos erros que ocorreram em suas janelas de documento. Atalhos de teclado são fornecidos para que o usuário possa navegar rapidamente grandes quantidades de código e ir diretamente para o local do problema. O Visual Studio também permite que cada erro de compilação seja vinculado a uma palavra-chave/ID de contexto da Ajuda específica para que o usuário possa ir diretamente para um tópico da Ajuda que forneça informações mais detalhadas sobre o erro.

Escreva erros de compilação claros e concisos:

• Use uma linguagem simples que explique o problema com pouco ou nenhum jargão do compilador. O texto de um erro de compilação não deve ser excessivamente técnico.

• Descreva possíveis causas. Por exemplo, "Faltam dois pontos entre a propriedade e o valor na declaração '(propriedade) : (valor)'."

• Forneça detalhes sobre possíveis correções. Se não houver espaço suficiente, detalhes adicionais podem ser colocados no tópico da Ajuda correspondente.

Componentes de uma mensagem de erro bem escrita

Use o serviço de diálogo do shell para mensagens de erro.

O uso do serviço de caixa de diálogo do shell permite controlar a aparência da mensagem, fontes em particular, sem grandes alterações em elementos individuais. Use os mecanismos IErrorInfo e relate-os usando IVsUIShell::SetErrorInfo/ReportErrorInfo.

Escolha uma apresentação de notificação eficaz e apropriada.

Use uma caixa de diálogo modal com um aviso crítico se uma ação imediata for necessária para evitar a perda de dados (notificação síncrona). Ícones críticos são reservados para situações em que fechar a mensagem sem lê-la pode levar a consequências negativas. A perda de dados é uma situação crítica que requer uma resposta em nível de alarme. O uso excessivo do ícone crítico dessensibiliza os usuários para sua importância. Se a mensagem de erro for de natureza informativa, considere alternativas para uma caixa de diálogo modal (notificação assíncrona).

Forneça uma explicação limpa e sucinta do motivo pelo qual o problema ocorreu, em vez de uma explicação técnica.

Sobrecarregar os usuários com detalhes técnicos na explicação os tornará mais propensos a ignorar mensagens de erro. Exemplos de boas mensagens:

• "Não é possível abrir o arquivo solicitado."

• "Não é possível conectar-se à Internet."

Forneça informações sobre como corrigir o problema.

Ofereça ao usuário sugestões de como corrigir o problema. Seja honesto com o usuário se não houver sugestões. Forneça links diretos para fontes on-line alternativas, como suporte técnico ou suporte da comunidade. Tente direcionar os usuários para informações on-line específicas pertinentes ao problema. Para uma ID de erro, considere vincular usuários a um thread de discussão sobre esse erro específico. Exemplos de boas mensagens:

• "Verifique se você está conectado à Internet e tente esta operação novamente."

• "Verifique se o arquivo existe e se você tem permissão para abri-lo."

Escreva uma mensagem curta e direta.

Uma mensagem de erro pode notificar, explicar e oferecer uma solução, mas ainda ser ignorada se for muito prolixa. Uma solução é usar a divulgação progressiva com um botão de detalhes. Por exemplo, forneça uma breve descrição/solução e, em seguida, coloque mais detalhes em um botão de detalhes. Se os usuários optarem por ler mais informações sobre o erro, eles poderão fazê-lo.

O idioma na mensagem deve ser:

• Domínio apropriado. Use a linguagem que o usuário entenderá. Mesmo que nossos clientes sejam desenvolvedores, eles muitas vezes não têm o contexto e a terminologia que temos.

• Específico. Evite palavras vagas e dê nomes e locais específicos dos objetos envolvidos. Por exemplo, uma mensagem de erro como "caractere é inválido" não é útil. Qual personagem? "Arquivo não encontrado." Qual arquivo?

• Cortês. Não culpe o usuário ou faça com que ele se sinta estúpido. Evite linguagem hostil ou ofensiva (matar, executar, encerrar, fatal, ilegal). Evite texto em maiúsculas, que muitas vezes é visto como gritaria e não é tão legível. Não use humor.

• Correto. Use ortografia e gramática corretas (mesmo em alfas). Os erros de digitação são pouco profissionais e constrangedores.

• Contextualmente apropriado. Use o texto do botão apropriado. Evite o botão "OK" e, em vez disso, use "Continuar" ou "Sim/Não".

Exemplos de mensagens de erro

Boa	Ruim
"O número que você discou não está mais em serviço. Verifique o número e disque novamente ou disque 0 para a operadora."	- "Erro (449): Número ilegal" - "Este erro de exceção não tratada indica que a operação foi concluída com êxito."

Acessando a Ajuda

Além da documentação no MSDN, um usuário do Visual Studio tem vários pontos de acesso para ajudar o usuário enquanto estiver na interface do usuário. Para garantir que esses pontos de acesso estejam consistentemente disponíveis, as equipes de recursos precisam aproveitar o sistema de Ajuda oferecido pelo ambiente. Esses pontos de acesso são:

• Texto instrucional e complementar em diálogos. Texto estático que fornece direção ou explicação, na superfície da interface do usuário ou disponível ao passar o mouse sobre um ícone da Dica de Informação.

• Ajuda F1 (somente editor). No editor do Visual Studio, um usuário pode confiar que, a qualquer momento, pressionar F1 exibirá um tópico da Ajuda específico para a seleção atual. Certifique-se de que os tópicos associados à F1 sejam apropriados e informativos.

• Hiperlinks para tópicos da Ajuda. Um hiperlink em uma caixa de diálogo, janela de ferramenta ou superfície de design que inicia um tópico para ajudar o usuário a aprender mais sobre uma tecnologia, recurso ou informações sobre como realizar uma tarefa.

• Mecanismos auxiliares da interface do usuário, como marcas inteligentes e caixas de diálogo de criação. Esses mecanismos ajudam o usuário a entender um elemento da interface do usuário ou facilitam uma tarefa, como marcas inteligentes ou caixas de diálogo do construtor.

• Botões de Ajuda da interface do usuário (preteridos). Um indicador visível na barra de título que dá acesso ao tópico da Ajuda F1 relacionado.

Texto

Texto instrucional e suplementar em diálogos

Em caixas de diálogo que oferecem suporte a tarefas complexas, pode haver a necessidade de fornecer texto instrucional dentro da interface do usuário, geralmente na parte superior da caixa de diálogo ou perto de controles complexos. Consulte Texto e terminologia da interface do usuário para obter detalhes sobre o estilo de escrita.

InfoDicas

Muitas vezes, o texto instrucional pode ser muito longo para ser posicionado no lugar na interface do usuário ou pode ser útil apenas para novos usuários, parecendo confuso para usuários experientes. Nesse caso, o texto instrucional/informativo deve ser colocado como uma dica de ferramenta em uma InfoTip.

As Dicas de Informações devem ser colocadas perto dos controles aos quais estão relacionadas e devem usar o ícone específico da Dica de Informação, que é discreto, mas perceptível.

Exemplo de uma dica de informação no Visual Studio

Mecanismos interativos de ajuda

Ajuda F1

A Ajuda F1 é necessária em um editor ou superfície de design, mas não em outro lugar no ambiente do Visual Studio.

Hiperlinks para tópicos da Ajuda

Os hiperlinks podem ser usados para executar uma ação, navegar no IDE ou iniciar a Ajuda em um navegador. Consulte Texto e terminologia da interface do usuário para obter detalhes sobre o idioma e 07.10.01 Botões e hiperlinks para obter diretrizes visuais e de layout.

Botões Ajuda [?] nas barras de título da caixa de diálogo (preterido)

Na maioria das vezes, os botões Ajuda [?] na barra de título das caixas de diálogo foram preteridos. Os tópicos da interface do usuário não fazem mais parte do nosso modelo de documento e, portanto, pode não haver um tópico relevante para vincular. Essencialmente, o botão da barra de título era a mesma coisa que a Ajuda F1, e isso não é mais necessário nas caixas de diálogo. Em alguns casos, isso ainda pode ser usado como um indicador de que há mais informações conceituais ou processuais disponíveis, embora hiperlinks sejam mais comumente usados na interface do usuário mais recente.

Diálogos criados através do ambiente

Muitas caixas de diálogo de shell são criadas através da função VBDialogBoxParam . Essa função compartilhada foi atualizada para ajudar a mover o botão Ajuda da caixa de diálogo para o botão ? , mantendo uma arquitetura compatível com versões anteriores e extensível.

Especificamente, a função VBDialogBoxParam examina o modelo de diálogo de um botão cuja ID é IDHELP (9) ou rótulo é Ajuda ou &Ajuda. Se um botão Ajuda for encontrado, ele ficará oculto e o estilo WS_EX_CONTEXTHELP será adicionado à caixa de diálogo, o que colocará o botão ? na barra de título da caixa de diálogo.

Quando a caixa de diálogo é criada, ela envia a opção de diálogo para uma pilha e invoca a caixa de diálogo com uma proc de caixa de diálogo de pré-processamento chamada DialogPreProc. Quando o botão ? é clicado, ele envia uma WM_SYSCOMMAND de SC_CONTEXTHELP para a caixa de diálogo. O DialogPreProc captura esse comando e o altera para uma mensagem WM_HELP , que é passada para o proc de diálogo original.

A maioria das caixas de diálogo criadas pelo ambiente tem um botão Ajuda na caixa de diálogo. Quando a caixa de diálogo é exibida, o botão Ajuda fica oculto automaticamente e somente o botão ? funciona. Se o botão ? for removido ou alterado no Windows, esta solução permite que você volte rapidamente para os botões de Ajuda originais.

Esta solução faz quatro suposições que podem causar bugs:

• O botão de ajuda da caixa de diálogo é IDHELP (9).

• A caixa de diálogo parece correta quando o botão Ajuda está oculto.

• A caixa de diálogo não substitui seu winproc.

• A caixa de diálogo não está incorporada dentro de outra caixa de diálogo.

  Se sua caixa de diálogo reside no msenv e não usa VBDialogBoxParam, investigue o aproveitamento do VBDialogBoxParam antes de implementar seu próprio manipulador.

Caixas de diálogo criadas por meio de outros pacotes

Você pode implementar sua própria solução para caixas de diálogo que residem fora do msenv. Para uma classe de diálogo compartilhada em seu VSPackage, considere mover o botão para a barra de título ou implementar um manipulador em cada caixa de diálogo. O código a seguir é um esqueleto de uma implementação para ajudá-lo a começar:

struct DLGPROCITEM
{
    FARPROC proc; // The info used to create the dialog.
    DLGPROCITEM* procPrev;
};

DLGPROCITEM* g_dlgProcStack = NULL;

// A dialog starter/wrapper function is used to push the new
// dialog proc to the top of our dialog proc stack.

int SomeDialogStarterFunction(hinst, id, proc, etc)
{
    if (g_dlgProcStack == NULL)
    {
        g_dlgProcStack = new DLGPROCITEM;
        g_dlgProcStack->procPrev = NULL;
    }
    else
    {
        DLGPROCITEM* procItem = new DLGPROCITEM;
        g_dlgProcStack->procPrev = g_dlgProcStack;
        g_dlgProcStack = procItem;
    }
}

// Pop this dialog proc off the dialog proc stack.

DialogBoxIndirectParam...(...)
{
    DLGPROCITEM* procItem = g_dlgProcStack->procPrev;
    delete g_dlgProcStack;
    g_dlgProcStack = procItem;
}

// A wrapper dialog procedure will allow us to capture the
// SC_CONTEXTHELP button on the title bar from Windows and
// forward it as a simple WM_HELP message back to the dialog.

INT_PTR CALLBACK DialogPreProc(HWND hwndDlg, UINT uMsg,
    WPARAM wParam, LPARAM lParam)
{
    if (uMsg == WM_SYSCOMMAND && wParam == SC_CONTEXTHELP)
    {
        uMsg = WM_HELP;
        wParam = 0;
        lParam = 0;
    }
    return CallWindowProc((WNDPROC)g_dlgProcStack->proc,
        hwndDlg, uMsg, wParam, lParam);
}

Botões de Ajuda no código gerenciado

Substituir o comportamento padrão do botão Ajuda da barra de título da janela é fácil no código gerenciado. Abaixo está um aplicativo de demonstração completo que demonstra esse comportamento. Em essência, você precisa substituir o método WndProc do formulário e, em seguida, disparar solicitações de ajuda F1 quando uma mensagem SC_CONTEXTHELP é interceptada.

using System;
using System.Windows.Forms;

public class HelpForm : Form
{
    private const int SC_CONTEXTHELP = 0xF180;
    private const int WM_SYSCOMMAND = 0x0112;

    public HelpForm()
    {
        this.ClientSize = new System.Drawing.Size(300, 250);
        this.HelpButton = true;
        this.MaximizeBox = false;
        this.MinimizeBox = false;
        this.Name = "HelpForm";
        this.Text = "Help Form";
    }

    protected override void WndProc(ref Message m)
    {
        if (m.Msg == WM_SYSCOMMAND && SC_CONTEXTHELP == (int)m.WParam)
            ShowHelp();
        else
            base.WndProc(ref m);
    }

    private void ShowHelp()
    {
        MessageBox.Show("F1 Help goes here.");
    }

     [STAThread]
    static void Main()
    {
        Application.EnableVisualStyles();
        Application.EnableRTLMirroring();
        Application.Run(new HelpForm());
    }
}

Confira também

• Fontes e formatação para Visual Studio
• Layout para Visual Studio
• Notificações e progresso do Visual Studio