Tabela de conteúdos

Padrões de documentação

Documentação Técnica, HELP e Release Notes

Em todas as versões deverão ser liberadas documentações técnicas, help do sistema e o release notes.
Como dentro do Help poderão haver links para a documentação técnica e quem normalmente faz a documentação técnica é o programador durante o desenvolvimento/correção das rotinas do Mentorweb, a documentação técnica deve ser feita antes do help do sistema.
Da mesma forma, dentro do release há menções sobre o help do sistema, então o help do sistema deve ser feito antes do release notes.
Desta forma, a ordem de documentação é:

  1. Documentação técnica;
  2. Help do sistema;
  3. Release notes;

Trechos de códigos

Sempre que na documentação for necessário colocar um trecho de código que o cliente deverá manipular, este trecho de código deve ser colocado dentro da tag <file> juntamente com o nome da linguagem de programação do codigo. Por exemplo:

config.xml
<configuracao>
	<so>WIN</so>
	<banco>MSSQL</banco>
	<pathEdusoft>C:\edusoft7</pathEdusoft>
	<pathTomcat>C:\edusoft7\tomcat7032</pathTomcat>
	<pathJava>C:\edusoft7\java7u9\bin</pathJava>
	<pathPerfil>C:\edusoft7\atualizador\Perfis</pathPerfil>
	<pathWar>C:\edusoft7\tomcat7032\wars</pathWar>
	<pathXml>C:\edusoft7\tomcat7032\conf\Catalina\localhost</pathXml>
	<proxyUse>false</proxyUse>
	<proxyHost></proxyHost>
	<proxyPort></proxyPort>
	<proxyUser></proxyUser>
	<proxyPass></proxyPass>
	<ambiente>Cliente</ambiente>
</configuracao>

Quando o trecho de código não tiver a necessidade de ser executado pelo cliente, o mesmo deve ser escrito dentro da tag <code> como no exemplo abaixo:

if (${PRORROGACAO} == 1 )
   Não aceitar após o vencimento.
else
   Multa de R$ ${TAXA_MULTA_REAL} após o vencimento. Juros de R$ ${TAXA_JUROS_REAL} ao dia.
end 

Imagens

Níveis e subníveis

Sempre que se iniciar uma nova página, deve-se colocar o titulo desta pagina com o cabeçalho de nível 1 e os demais títulos e subtítulos devem estar com os cabeçalho de nível 2 em diante

Exemplo:

====== Título de nível 1 ======
===== Título de nível 2 =====
==== Título de nível 3 ====
=== Título de nível 4 ===
== Título de nível 5 ==

Título de nível 1

Título de nível 2

Título de nível 3

Título de nível 4

Título de nível 5

Criar a documentação técnica

No help terá as informações a nível de usuário, para uso interno utilizaremos um sessão chamada “Documentação técnica”, nessa sessão os clientes não terão acesso. Porém para criar essa documentação técnica a “Editor” deverá seguir alguns padrões.

1º Passo: Ir na pasta da versão dentro de Documentação técnica, e criar/alterar um tópico com a rotina que será documentada.

2º Passo: Criar uma sessão chamada documentação técnica e apontar para um link interno que foi criado no primeiro passo.

* [[help:documentacao_tecnica:6.0:atualizador:atualizador|Documentação Técnica]] (Acesso restrito) :!: </code>

Onde:

Essa “url” é o caminho aonde está a documentação técnica.