Guia de Estilo¶

As seguintes regras visam garantir a consistência do MASTG:

Mantenha o conteúdo factual, breve e focado. Evite duplicar outras seções do guia;
Abstenha-se de divulgar ferramentas ou serviços comerciais;
Ao fornecer instruções técnicas, dirija-se ao leitor na segunda pessoa.

Redação Técnica

Recomendamos que você faça estes cursos gratuitos da Google ao escrever ou revisar conteúdo para o projeto MAS:

1. Como Escrever Conteúdo¶

Princípios Básicos¶

Garanta que o conteúdo tenha coesão e coerência:

Vincule ideias de forma clara e lógica.
Certifique-se de que cada parágrafo faça sentido por si só e se encaixe com os anteriores e posteriores.
Corte palavras desnecessárias. Use linguagem clara e concisa em vez de frases longas ou prolixas.
Estruture o conteúdo para facilitar a varredura visual. Use marcadores em vez de parágrafos densos quando possível.
Converta a voz passiva para ativa sempre que apropriado.
Mantenha cada parágrafo focado em um único tópico ou ideia.
Inicie cada seção com o ponto principal para orientar o leitor.
Use corretamente os sinais de pontuação, incluindo vírgulas, parênteses, dois-pontos, travessões e ponto e vírgula.

Quantidade de Conteúdo¶

A medida primária para a quantidade de conteúdo em uma página deve ser baseada no propósito que ela serve.

Use páginas curtas¶

Aquelas contendo uma ou duas telas de texto no máximo. Os usuários estão escaneando em busca de opções de links. Use páginas mais longas (que exigem mais rolagem ou leitura) em níveis mais profundos do capítulo, onde o conteúdo pode ser impresso e lido posteriormente.

Para seções muito grandes de informação¶

Considere criar um documento de apoio e vincular a ele a partir da página, em vez de exibir todas as informações diretamente na página.

Neutralidade de Gênero¶

O MASTG alcança todos os tipos de pessoas em todo o mundo. Para garantir inclusividade e diversidade, evite usar o seguinte em todo o livro:

ela / dela / suas / si mesma
ele / dele / seus / si mesmo

Ou qualquer outra construção como "ele/ela", "e/a", "dele ou dela". Em vez disso, use as seguintes alternativas neutras em termos de gênero:

Omita o pronome se possível: "O usuário se autentica usando ..." -> "O usuário autentica usando ..."
Substitua pronomes por "o" ou "um": "Quando o usuário insere sua senha ..." -> "Quando o usuário insere a senha ..."
Use substantivos e pronomes no plural: "Um atacante usará seu dispositivo com jailbreak ..." -> "Atacantes usarão seus dispositivos com jailbreak ..."
Use a segunda pessoa: "Se o atacante executar este código, ele pode contornar ..." -> "Se você executar este código, pode contornar ..."
Use o imperativo: "Um desenvolvedor nunca deve usar ... em seu código" -> "Nunca use ... em seu código!"

Atualidade do Conteúdo¶

Manter conteúdo preciso e atualizado estabelece os entregáveis do OWASP MAS como uma fonte de informação confiável e credível.

Ao usar dados estatísticos em sua página, garanta que a informação esteja atualizada e seja acompanhada pela fonte da qual foi derivada, juntamente com a data em que os dados foram compilados.

Conteúdo para Plataforma Digital Versus para Impressão¶

Escreva conteúdo conciso que o usuário possa ler de forma rápida e eficiente. Para conteúdo digital - crie páginas mais curtas que sejam interligadas. Se seu conteúdo provavelmente será impresso, crie uma página longa.

Público-Alvo¶

Escreva para um público internacional com um nível básico de compreensão técnica, ou seja, eles têm um telefone móvel e sabem como instalar um app. Evite gírias ou frases difíceis de traduzir para garantir que o conteúdo seja acessível a leitores que não são falantes nativos de inglês.

Contexto e Orientação¶

Informe aos usuários onde eles estão em cada página. Estabeleça o tópico usando um cabeçalho de página único.

Inclua uma introdução clara e concisa sempre que possível.

Vincule a informações de fundo quando necessário.

Escreva para que as Pessoas Leiam com Prazer¶

Use os seguintes métodos para aumentar a capacidade de varredura visual:

Use alinhamento à esquerda para títulos, subtítulos e texto
Vincule onde apropriado
Use listas em vez de parágrafos sempre que possível
Use travessões - em vez de asteriscos * para listas
Inclua apenas uma ideia principal em cada parágrafo
Coloque a informação mais importante no topo
Inicie a página com a conclusão e um breve resumo do conteúdo restante
Use cabeçalhos quando aplicável
Use palavras curtas e simples que sejam diretas
Seja conciso e focado

Para páginas mais longas, use as seguintes ferramentas para tornar a página facilmente escaneável:

Links âncora
Subtítulos e links relevantes
Conteúdo com marcadores
Gráficos significativos ou citações para quebrar blocos maiores de texto
Links finais

Uso Eficaz de Listas¶

Ao apresentar seu conteúdo em formato de lista:

Use listas numeradas quando a ordem das entradas for importante.
Use listas com marcadores sempre que a ordem das entradas não for importante.
Geralmente, limite o número de itens em uma única lista a no máximo nove.
Geralmente, limite as listas a no máximo dois níveis: primário e secundário.
Pontue e coloque em maiúsculas os itens da lista de forma consistente (CMOS 6.124-6.126).
Não adicione pontuação final a itens de lista que não são frases completas, a menos que completem a frase que introduz a lista.
Use maiúsculas e pontuação final apropriadas para itens de lista que individualmente formam frases completas.
Se os itens da lista completam uma frase introdutória, termine cada um (exceto o último item) com vírgula e não adicione "e" após o penúltimo item. Termine o último item com pontuação final apropriada (normalmente um ponto).

Convenções de Numeração¶

Ao usar um número entre zero e dez, escreva o número por extenso (por exemplo, "três" ou "dez").

Ao usar qualquer número maior que dez, use a versão numérica (por exemplo, "12" ou "300").

2. Idioma¶

Ortografia e Terminologia Americana¶

Use ortografia e terminologia americana.

Altere toda ortografia e terminologia britânica para os equivalentes americanos quando aplicável. Isso inclui "toward" (EUA) vs. "towards" (UK), "among" (EUA) vs. "amongst" (UK), "analyze" (EUA) vs. "analyse" (UK), "behavior" (EUA) vs "behaviour" (UK), etc.

Plurais¶

Aderir às regras padrão de gramática e pontuação quando se trata de pluralização de palavras típicas.

O plural de anos calendário não leva apóstrofo antes do "s". Por exemplo, a forma plural de 1990 é 1990s.

Capitalização de Títulos¶

Seguimos as regras de capitalização de títulos do "Chicago Manual of Style":

Coloque em maiúscula a primeira e a última palavra em um título, independentemente da classe gramatical
Coloque em maiúscula todos os substantivos (app, encryption, package), pronomes (you, she, it), verbos (analyze, compile, inspect), adjetivos (active, insecure, weak), advérbios (immediately, quietly) e conjunções subordinativas (as, because, although)
Use minúsculas para "to" como parte de um infinitivo
Use minúsculas para todos os artigos (a, the), preposições (to, at, in, with) e conjunções coordenativas (and, but, or)

Em caso de dúvida, você pode verificar a capitalização adequada em https://titlecaseconverter.com/.

Padronização¶

O projeto MAS (MASVS, MASTG, MASWE) busca uma redação consistente que seja clara e inequívoca no contexto. No entanto, devido ao tamanho do projeto, pode haver palavras ou abreviações usadas de forma inconsistente que precisam ser padronizadas. Se for esse o caso, envie um pull request para que possamos discutir e sugerir o que deve ser usado.

Contractions¶

Use as seguintes contrações comuns:

are not -> aren't
cannot -> can't
could not -> couldn't
did not -> didn't
do not -> don't
does not -> doesn't
has not -> hasn't
had not -> hadn't
have not -> haven't
is not -> isn't
it is -> it's
that is -> that's
there is -> there's
was not -> wasn't
were not -> weren't
will not -> won't
would not -> wouldn't
you are -> you're
you have + verb -> you've + verb
you will -> you'll

Abreviações¶

Abreviações incluem acrônimos, inicialismos, palavras abreviadas e contrações.

Escreva por extenso o termo na primeira vez que for usado, seguido da abreviação entre parênteses. Exemplo: OWASP Mobile Application Security Testing Guide (MASTG). Usos subsequentes no mesmo capítulo podem incluir apenas a abreviação.
Se aparecer apenas uma vez no conteúdo, escreva o termo por extenso em vez de usar a abreviação.
Em títulos e cabeçalhos, use a abreviação, mas certifique-se de introduzi-la adequadamente (veja acima) no texto seguinte.
Use "a" ou "an" dependendo da pronúncia do acrônimo. Exemplo: a DLL, an APK, a URL, a SQL.
Adicione um "s" para a forma plural, a menos que a abreviação já represente um substantivo plural. Exemplo: the APIs, CSS (não CSSs).
Se a abreviação for mais conhecida do que o termo por extenso, use apenas a abreviação. Exemplo: PDF, URL, USB, ZIP.

O seguinte trecho demonstra a maioria desses pontos:

## Arquivos JAR

Arquivos JAR (Java ARchive) são [...]

APKs são compactados usando o formato ZIP. Um APK é uma variação de um arquivo JAR [...]

Para formatos de arquivo comumente usados, como APK, IPA ou ZIP, não se refira a eles como ".apk", ".ipa" ou ".zip", a menos que esteja se referindo explicitamente à extensão do arquivo.

Referenciando versões do Android¶

Use o seguinte formato ao se referir a uma versão do Android: Android X (API level YY). O uso do nome descritivo (Ex: Oreo) é desencorajado.

Ex: Android 9 (API level 28)

Dirigindo-se ao Leitor em Casos de Teste¶

Ao longo do guia, você pode querer se dirigir aos leitores para dizer o que fazer ou o que devem observar. Para qualquer caso desse tipo, use uma abordagem ativa e simplesmente dirija-se ao leitor usando "você".

Correto: Se você abrir o arquivo AndroidManifest.xml, verá uma tag Application principal, com os seguintes atributos: atr1, atr2 e atr3. Se você executar o seguinte comando, verá que atr1 é realmente perigoso: [...].

Errado: O arquivo AndroidManifest.xml contém uma tag Application, com os seguintes atributos: atr1, atr2 e atr3. O comando abaixo mostra que atr1 é perigoso: [...].

Errado: Se abrirmos o arquivo AndroidManifest.xml, veremos uma tag Application principal, com os seguintes atributos: atr1, atr2 e atr3. Se executarmos o seguinte comando, veremos que atr1 é realmente perigoso: [...].

3. Referências Externas¶

Links da Web¶

Use o formato de link inline do markdown (A) [TEXTO](URL "TÍTULO") ou (B) [TEXTO](URL).

Por exemplo:

As [diretrizes de modelagem de ameaças definidas pela OWASP](https://owasp.org/www-community/Threat_Modeling "OWASP Threat Modeling") são geralmente aplicáveis a apps móveis.

Ao usar (A), certifique-se de escapar caracteres especiais como apóstrofo (\') ou aspas simples (`), caso contrário o link será quebrado no Gitbook.

Uso errado, veja "iPhone's":

[UDID do seu dispositivo iOS via iTunes](https://medium.com/@igor_marques/how-to-find-an-iphones-udid-2d157f1cf2b9 "How to Find Your iPhone's UDID")

Uso correto, veja "iPhone\'s":

[UDID do seu dispositivo iOS via iTunes](https://medium.com/@igor_marques/how-to-find-an-iphones-udid-2d157f1cf2b9 "How to Find Your iPhone\'s UDID")

Ao adicionar links à seção "Referências" no final dos capítulos, use - Título - <url>. Isso é necessário para forçar o latex a imprimir URLs corretamente para o PDF.

Por exemplo:

- adb - <https://developer.android.com/studio/command-line/adb>

Livros e Artigos¶

Para livros e artigos, use o seguinte formato: [#shortname].

E inclua a referência completa na seção "Referências" no final do arquivo markdown manualmente. Exemplo:

Um algoritmo de criptografia ofuscado pode gerar sua chave (ou parte da chave)
usando dados coletados do ambiente [#riordan].

E sob a seção "Referências" no final dos capítulos:

- [#riordan] -  James Riordan, Bruce Schneier. Environmental Key Generation towards Clueless Agents. Mobile Agents and Security, Springer Verlag, 1998

Artigos:

A forma geral para citar relatórios técnicos é colocar o nome e localização da empresa ou instituição após o autor e título e dar o número do relatório e data no final da referência.

Formato Básico:

- [shortname] J. K. Author, "Title of report," Abbrev. Name of Co., City of Co., Abbrev. State, Rep. xxx, year

- [shortname] \[Autor(es)\], \[Título\] - Link

Livros:

- [shortname] \[Autor(es)\], \[Título\], \[Publicado\], \[Ano\]

- [examplebook] J. K. Author, "Title of chapter in the book," in Title of His Published Book, xth ed. City of Publisher, Country if not USA: Abbrev. of Publisher, year, ch. x, sec. x, pp. xxx-xxx.

NOTA: Use et al. quando três ou mais nomes forem fornecidos

ex.

- [klaus] B. Klaus and P. Horn, Robot Vision. Cambridge, MA: MIT Press, 1986.
- [stein] L. Stein, "Random patterns," in Computers and You, J. S. Brake, Ed. New York: Wiley, 1994, pp. 55-70.
- [myer] R. L. Myer, "Parametric oscillators and nonlinear materials," in Nonlinear Optics, vol. 4, P. G. Harper and B. S. Wherret, Eds. San Francisco, CA: Academic, 1977, pp. 47-160.
- [abramowitz] M. Abramowitz and I. A. Stegun, Eds., Handbook of Mathematical Functions (Applied Mathematics Series 55). Washington, DC: NBS, 1964, pp. 32-33.

4. Referências Dentro do Guia¶

Para referências a outros capítulos no MASTG, simplesmente nomeie o capítulo, por exemplo: Veja também o capítulo "Teste Básico de Segurança", Veja a seção "Apktool" no capítulo "Teste Básico de Segurança" etc. O MASTG deve ser conveniente para ler como um livro impresso, então use referências internas com moderação. Alternativamente, você pode criar um link para a seção específica:

Veja a seção "[Pacotes de Apps](0x05a-Platform-Overview.md#app-bundles)" no capítulo ...

Note que nesse caso a âncora (tudo após o #) deve estar em minúsculas e os espaços devem ser substituídos por hífens.

5. Inserir Imagens¶

Imagens devem ser sempre um elemento HTML <img em vez do formato usual de imagem em markdown.

src sendo o primeiro valor.
uma width pode ser especificada.
elas devem ser incluídas no diretório correspondente, por exemplo, em Document/Images/Chapters para capítulos do MASTG.

Por exemplo:

<img src="Images/Chapters/0x05b/r2_pd_10.png" width="80%" />

6. Convenções de Pontuação¶

Letra Minúscula ou Maiúscula Após Dois-Pontos¶

O Chicago Manual of Style (6.61: Lowercase or capital letter after a colon) diz: use minúsculas na primeira palavra, a menos que seja um nome próprio ou o início de pelo menos duas frases completas ou uma pergunta direta.

Uso da Vírgula Serial¶

Use uma vírgula serial antes de "e" para o último item em uma lista corrida de três ou mais itens. Por exemplo:

Compramos maçãs, laranjas e tomates na loja.

Aspas e Apóstrofos¶

Use aspas duplas retas, aspas simples retas e apóstrofos retos (não aspas/apóstrofos curvos).

Termos Técnicos¶

Soletre/pontue termos técnicos específicos como são usados pela empresa (por exemplo, use o site da empresa).

Em ordem de preferência, soletre/pontue termos técnicos genéricos de acordo com

Merriam Webster's Collegiate Dictionary, 11ª edição.
Microsoft Manual of Style, 4ª edição
foldoc.org (Free Online Dictionary of Computing)

Forma Substantiva	Forma Adjetiva
App Store	NA
backend	backend
Base64	Base64-
black box	same
Bundle ID	NA
bytecode	NA
client side	client-side
codebase	same
code signing	same
command line	same
disassembler	NA
end users	NA
file name	same
macOS	NA
OS X	NA
pentest	same
PhoneGap	NA
Python	NA
repackage	NA
runtime	same
server side	server-side
snapshot length	NA
use case	same
Wi-Fi	same
white box	same

7. Comentários¶

Citações em bloco do Markdown podem ser usadas para comentários nos documentos usando >

> Este é um bloco de citação

8. Código e Comandos de Shell¶

Use blocos de código ao incluir código de exemplo, comandos de shell e caminhos. Em Markdown, blocos de código são denotados por três crases (```). O GitHub também suporta realce de sintaxe para uma variedade de linguagens. Por exemplo, um bloco de código Java deve ser anotado da seguinte forma:

```java
public static void main(String[] args) { System.out.println(" Hello World!"); } } ;
```

Isso produz o seguinte resultado:

public static void main(String[] args) { System.out.println(" Hello World!"); } }

Ao incluir comandos de shell, certifique-se de usar a linguagem correta para realce de sintaxe (por exemplo, shell ou bash) e remova qualquer prompt (nome do host, nome de usuário, ...) dos comandos, por exemplo:

```shell
echo 'Hello World'
Hello World
```

Quando um comando requer parâmetros que precisam ser modificados pelo leitor, envolva-os com colchetes angulares:

adb pull <arquivo_remoto> <destino>

Palavras-Chave no Texto¶

Quando não ocorrem em um bloco de código, coloque as seguintes palavras-chave relacionadas a código entre crases (``), aspas duplas retas (""), ou deixe sem pontuação de acordo com a tabela:

Crases	Aspas Duplas	Sem Pontuação
nomes de funções	títulos de seções	nome do aplicativo
nomes de métodos	títulos de capítulos	nomes de pastas
comandos	títulos de livros	endereços de memória (por exemplo, 0x100044520)
nomes de classes	valores de flags (por exemplo, "true", minúsculas)
nomes de blocos	opções de comando (por exemplo, opção "help")
nomes de flags	item único de menu (por exemplo, menu "Home")
nomes de arquivos	mensagens de erro do sistema
nomes de pacotes
caminhos de arquivos
senhas
números de porta
nomes de binários
argumentos de métodos/funções
argumentos ou valores de retorno de métodos/funções (por exemplo, `true`, `0`, `YES`)
atributos XML (por exemplo, `get-task-allow` em Plists do iOS, `"@string/app_name"` em Manifests do Android)
valores de atributos XML (por exemplo, `android:label` em Manifests do Android)
nomes de propriedades
nomes de objetos
chamadas de API
nomes de interfaces

Se substantivos entre crases estiverem no plural, coloque o "s" após a segunda crase (por exemplo, RuntimeExceptions). Não adicione parênteses, colchetes ou outra pontuação a quaisquer palavras-chave que estejam entre crases (por exemplo, main não main()).

Navegação¶

Ao se referir a qualquer elemento de interface do usuário por nome, coloque seu nome em negrito, usando **<nome>** (por exemplo, Home -> Menu).