Diretrizes para a redação de artigos

Então você gostaria de contribuir para o manual do MuseScore 4 - ótimo! Estamos muito felizes por você estar aqui.

Esta página contém diretrizes breves para começar a escrever artigos. Por favor, leia esta página atentamente antes de editar qualquer coisa em nosso manual. Esta informação destina-se a ajudar, mas se você tiver dúvidas sobre qualquer coisa ou tiver alguma pergunta, por favor, junte-se à discussão no fórum de Documentação.

Estrutura - Princípios gerais

Cada página deve explicar um único tópico de forma mais ou menos completa. Se uma página parecer estar ficando muito longa, tente dividi-la em páginas separadas.

Não todas as páginas são idênticas, mas manter o seguinte em mente pode ajudar a estruturar o conteúdo da sua página de uma forma que seja fácil de entender para o leitor:

Comece com uma visão geral

Iniciar sua página com uma visão geral pode ajudar a introduzir um tópico antes de entrar em detalhes. As visões gerais geralmente não precisam de um título de seção.

Estabeleça uma hierarquia

Pense no que a maioria dos usuários estará tentando realizar e por que eles podem estar consultando o manual em busca de informações. Coloque soluções para as tarefas mais comuns no topo da página; informações menos frequentemente necessárias podem ficar na parte inferior.

Agrupe informações logicamente

Conceitos relacionados devem ser discutidos juntos. Isso pode, às vezes, exigir que recursos menos comuns sejam discutidos ao lado dos mais comuns, mas tudo bem.

Concentre-se nas tarefas do usuário, não apenas nos componentes da interface do usuário

Por exemplo, uma seção sobre "Criação de armaduras de clave personalizadas" é melhor do que uma seção chamada "Usando a paleta mestra".

Crie uma tabela de conteúdos

Certifique-se de ativar a opção "Gerar uma tabela de conteúdos" para todas as páginas do manual.

Títulos

Em um esforço para garantir a consistência de estilo para as páginas escritas pela comunidade, já fornecemos títulos em muitas páginas. Por favor, organize seu conteúdo dentro dessa estrutura. Para páginas que não têm títulos, sinta-se à vontade para criar os seus de uma forma semelhante à usada em outros lugares.

Por razões de acessibilidade, os títulos nunca devem ser formatados em texto negrito comum. Todos os títulos precisam ser formatados como tags com significado semântico.

Todas as páginas começam por padrão com um Título 1. Portanto, o primeiro título de seção que você inserir sempre será um Título 2. Por favor, também não pule níveis de título (Por exemplo, adicionando um Título 4 após um Título 2).

Por fim, tente sempre começar seus títulos com um verbo. Por exemplo, "Adicionando assinaturas de compasso" em vez de "Assinaturas de compasso"

Conteúdo

O manual do MuseScore contém amplamente dois principais tipos de informações: material descritivo e instruções orientadas para objetivos.

Material descritivo

Isso é usado para explicar diferentes áreas do programa. Por exemplo,

Uma Paleta é uma pasta que contém símbolos musicais que podem ser aplicados à partitura. As paletas padrão do MuseScore contêm coleções de símbolos relacionados, mas você pode personalizar as paletas para exibir quase qualquer tipo de símbolo, linha ou texto.

O material descritivo tende a ser mais longo e mais "desenvolvido", mas ainda pedimos que você use linguagem simples e clara sempre que possível.

Instruções orientadas para objetivos

Essas instruções explicam como realizar uma tarefa específica. As instruções devem ser o mais curtas e diretas possível, geralmente na forma de uma lista numerada. Por exemplo,

Para criar uma nova paleta

1. Abra a guia paletas
2. Clique em Adicionar paletas
3. Clique em Criar paleta personalizada
4. Dê um nome à sua nova paleta e clique em Criar

Observe que usamos texto em negrito para componentes nomeados da interface do usuário, incluindo menus. Atalhos de teclado, como Ctrl+S, são formatados com tags <kbd> (consulte Sintaxe).

Ao escrever instruções orientadas para objetivos, por favor:

• Use apenas listas numeradas (sem pontos)
• Comece cada instrução numerada com um verbo
• Escreva apenas uma tarefa/direção por item numerado

Por exemplo, em vez de escrever isto:

1. Abra a guia paletas e clique em Adicionar paletas

Por favor, escreva isto:

1. Abra a guia paletas
2. Clique em Adicionar paletas

Certifique-se de incluir opções de teclado nas instruções orientadas para objetivos, sempre que essas opções existirem. Isso é especialmente importante para melhorar a acessibilidade do programa.

Uso de mídia não escrita

O uso de mídia não escrita é incentivado como complemento às descrições escritas. Isso inclui:

• GIFs animados
• Capturas de tela de partes relevantes da interface do usuário

Criação de GIFs animados

Os GIFs animados oferecem muitas vantagens em relação às capturas de tela e vídeos, uma vez que mostram em um curto período de tempo a sequência de ações necessárias para realizar uma tarefa específica. Existem muitas ferramentas disponíveis para criar GIFs, no entanto, recomendamos o seguinte fluxo de trabalho para garantir qualidade de imagem nítida e clara, mantendo o tamanho do arquivo o mais pequeno possível (idealmente <2MB por GIF).

• Use apenas a interface do MuseScore 4 e configure sua aparência para o modo escuro com destaques azuis (para obter consistência em todo o manual)
• Planeje e ensaie os cliques do mouse e os atalhos de teclado que você usará, com o objetivo de demonstrar as etapas necessárias no menor tempo possível (idealmente <10s)
• Use uma ferramenta gratuita como gifcap para gravar o conteúdo de sua tela
• Use uma ferramenta gratuita como KeyCastr para gravar as teclas (quando necessário)
• Mostre apenas a quantidade de IU necessária para demonstrar uma tarefa específica

Vinculação a outras páginas

É realmente útil vincular a outras páginas no manual. Você pode fazer isso sempre que mencionar uma parte diferente da interface do usuário, ou mesmo ao se referir a versões anteriores do manual.

Existe um processo específico para adicionar links para outras páginas do manual, o que permitirá redirecionamentos precisos, independentemente da versão do idioma em leitura.

Use a sintaxe correta

[node:######,title="Nome da página que você deseja vincular"]

ou, para vincular a um título específico dentro da página:

[node:######,fragment="heading-slug",title="Nome da página que você deseja vincular"]

Vincule para o número de nó da página, não para a URL da página

Para encontrar o número de nó de uma página:

1. Abra a página desejada em seu navegador
2. Clique no ícone dos "três pontos" no canto superior direito da página
3. Clique em Editar no menu de contexto que aparece
4. Clique na barra de pesquisa do seu navegador para ler a URL

Você encontrará o número de nó da página na URL visível nesta tela de edição (sim, ele só aparece na tela de edição). Vai parecer algo assim:

Você pode usar isso como um marcador em seus favoritos

javascript:void function()
{prompt("",`[node:${drupalSettings.path.currentPath.replace("node/","")}${document.querySelector("meta[property=\"og:title\"]").content?`,title="${document.querySelector("meta[property=\"og:title\"]").content}"`:""}${window.location.hash?
`,fragment="${decodeURIComponent(window.hash).replace("#","")}"`:""}]`)}();

Tirado de Marcador de nó, título, fragmento

Sintaxe

O manual é escrito em MarkDown com algumas tags HTML permitidas.

Se você não está familiarizado com o MarkDown, não leva muito tempo para aprender. Comece por ler esta página primeiro (uma conta no MuseScore é necessária para visualizar adequadamente o conteúdo dessa página; observe também que você não pode mais usar HTML filtrado).

Alguns exemplos para elementos além do MarkDown:

Teclas

<kbd><kbd>A</kbd></kbd>, parece A. (Veja Escrevendo atalhos de teclado abaixo.)

Combinações de teclas

<kbd><kbd>Shift</kbd>+<kbd>A</kbd></kbd>, parece Shift+A. (Veja Escrevendo atalhos de teclado abaixo.)

Botões

<kbd><samp class="button">Propriedades de Estilo Avançado...</samp></kbd>, parece Propriedades de Estilo Avançado..., mas esta forma específica não é usada no manual do MuseScore 4 (em vez disso, use negrito para o texto que aparece no programa).

Entradas de menu

__Arquivo→Abrir__, parece Arquivo→Abrir

Imagens

<img src="URL da imagem" alt="Nome do arquivo descrição" width="500px"/>, pode ser uma alternativa útil para imagens inline, onde a largura da imagem precisa ser especificada

Escrevendo atalhos de teclado

Use a sintaxe <kbd> descrita acima e siga estas diretrizes:

• Por razões de acessibilidade, use sempre palavras em vez de símbolos para os nomes de todas as teclas de espaço em branco, teclas de seta e teclas de modificação.

  • Bom: Cmd+Space; Win+Return; Shift+Tab

  • Ruim: ⌘+ ; ⊞+⏎; ⇧+↹

• Para teclas que representam caracteres imprimíveis, o caractere apropriado deve ser usado (por exemplo, escreva $ e não Dollar).

• Use abreviações comuns como Ctrl, Cmd, Esc, Del, PgDn. Não abrevie nomes de teclas que normalmente não são abreviados.

• Exceto quando for importante, prefira Return em vez de Enter e Del em vez de Backspace.

• Para combinações, escreva as teclas de modificação nessa ordem: Win+Ctrl+Alt+Shift+Fn+… (Mac: Ctrl+Cmd+Option+Shift+Fn+…).

Quando estiver em dúvida, consulte Atalhos de teclado padrão para a forma canônica de escrever nomes de teclas e combinações.

Deixando uma mensagem de registro de revisão

Finalmente, sempre que você fizer uma alteração em uma página (por menor que seja!), por favor, deixe uma mensagem concisa que descreva brevemente as mudanças que você fez. Por exemplo,

• Adicionado conteúdo sobre xxx
• Adicionadas imagens
• Corrigido conteúdo
• Adicionadas tags de teclado

Deixe esta informação no campo de texto Mensagem de registro de revisão no painel direito da visualização de Editar para cada página: