A batalha da documentação
Autora: Maria José Resmer - condensado por Eliane do Rocio Teixeira
( Stephen F. Jacobus)
Quando você fala com pessoas de processamento de dados e lê periódico referentes ao assunto é comum ouvir os mesmos tipos de questões serem repetidas.
Como eu consigo que os analistas/programadores documentem seus sistemas?
Como eu consigo que as áreas usuárias leiam as documentações que damos a eles e sigam os procedimentos?
Estas questões sempre se repetem porque elas são inadequadas e ignoram a profundidade do problema..
RESISTÊNCIA PARA PRODUZIR DOCUMENTAÇÃO:
Ao se trabalhar com pessoas de Processamento de Dados, descobre-se que:
1 – Algumas delas sentem dificuldades para escrever.
2 – Muitos técnicos não gostam de documentar seus trabalhos.
3 – Muitos técnicos são orientados para tarefas, e não para pessoas.
Considerando que os técnicos precisam acompanhar a elaboração da documentação de sistema, essa se apresenta como uma “batalha” adicional, um impedimento para terminar o projeto em tempo. Então acaba resultando um trabalho pesado. A documentação fica resumida a um agrupamento de informações, nem sempre aprofundadas, que prejudicam a sua qualidade.
As seguintes regras são importantes para assegurar uma documentação de sistemas útil e gerada em tempo hábil:
REGRAS PARA DOCUMENTAÇÃO EM PROCESSAMENTO DE DADOS:
1- Definir responsabilidade específica para desenvolvimento e liberação de documentação.
2 – Empregar documentadores experientes, ou treinar seus próprios ( e aceitar alguns atrasos).
3 – Dar autoridade aos documentadores.
4 – Insistir que os usuários sejam incluídos no desenvolvimento e revisão das documentações desde o início.
5 – Possibilitar que o pessoal de marketing reveja quaisquer documentos que irão afetar sua imagem como o cliente. Isto inclui documentos técnicos.
6 – Testar, ao mesmo tempo, a nova documentação do sistema.
7 – Desenvolver, forçar a utilização e revisar padrões de documentação.
8 – Tomar uma decisão cuidadosa a respeito da centralização ou descentralização do grupo de documentação.
9- Designar um coordenador de documentação em cada departamento, para receber documentações.
10 – Dar, ao coordenador do departamento de documentação, autoridade para periodicamente avaliar os tipos e adequação das documentações em uso, quanto à facilidade e divisões.
Também é importante destacar o cuidado que as empresas devem em desenvolver Padrões de Documentação que especifiquem o que deve ser incluído em certos tipos de documentação.
Padrões na Documentação são úteis:
* Se eles não forem muito genéricos ( tentando abranger todos os tipos de documentação).
* Se eles definirem o processo de revisão para documentação.
* Se responsabilidades de efetuar provisões nos padrões forem especificamente incluídas.
* Se responsabilidades para manter o padrão corrente tiverem sido determinadas.
* Se autoridade para impor um padrão for designada para um grupo específico.
* Se autoridade para revisar documentação, em um intervalo de seis a doze meses, for designada a um grupo específico.
Não é tarefa pequena, certo? Difícil de fazer, porque isso requer interagir com outros departamentos, envolve muita autoridade, e requer um grande comprometimento com documentação, por parte do administrador. Toma tempo e vontade de negociar.
Essa questão de negociação envolve desde a revisão de um manuscrito, passando por uma elaboração preliminar até a condução a uma revisão final, para assegurar que a documentação ainda esteja atualizada.
Inicialmente, a revisão será feita pelo chefe do documentador. As revisões posteriores serão feitas por outros departamentos e usuários. Comentários são “retornados” ao documentador que incorpora as mudanças, quando apropriadas, e contata os que revisaram para clarear as dúvidas.
Em resumo, escrita técnica requer considerável habilidade, e ainda algum tato.
Portanto, um candidato para a posição de documentador deve ser selecionado cuidadosamente e não de um grupo de trabalhadores do escritório.
DOCUMENTAÇÃO CENTRALIZADA X DESCENTRALIZADA:
A questão aqui é: deve-se ter um grupo de documentadores em cada departamento, ou criar um departamento separado (centralizado) que é independente do controle de sistemas, operação ou administração?
Não há uma resposta para todas as situações. Se existirem grupos de documentação esperados ficará difícil a qualquer um, exceto ao auditor, avaliar e controlar a qualidade da documentação. Isto é particularmente certo se as relações interdepartamentais forem difíceis.
O analista e o documentador podem intercambiar material técnico, mas mudar a documentação básica torna-se uma questão política.
De outro lado, pequenos grupos dentro de cada departamento pode resultar em um relacionamento “fraternal” com os empregados técnicos. O resultado pode ser que o fluxo de informação para e o documentador seja facilitado enormemente. Quando mais a documentação incluir os usuários no ciclo, mais facilmente as coisas sairão como eles querem. Contudo, cabe ao documentador a habilidade no relacionamento com o usuário, evitando opiniões estremadas que venham a comprometer a limitar a utilidade da documentação.
MAIS X MENOS:
Esta questão é mostrada de várias formas:
. Qual o volume adequado da documentação?
. Que vantagens são obtidas através da documentação?
. Como podemos diminuir a quantia de papéis “voando” à nossa volta?
. Como podemos ter certeza que a empresa dispõe do tipo de documentação adequada?
Essas questões diferem conforme a ocasião, representando diferentes suposições relativas à documentação. Por isso, antes de respondê-las, devemos levar em consideração os seguintes pontos:
1 – CADA NOVO SISTEMA E CADA MUDANÇA NO SISTEMA DEVEM SER DOCUMENTADOS
Em muitos casos, isso significa editar páginas de mudança e periodicamente reeditar toda a documentação.
2 – DOCUMENTAÇÃO DEVE SER EFICIENTE PARA QUE O LEITOR POSSA, RAPIDAMENTE ENCONTRAR O QUE PRECISA.
Entretanto, essa documentação também deve ser acessível o suficiente para que o leitor compreenda o conteúdo sem conhecimento prévio de um vocabulário especial. Isto significa que o documentador deve ter cuidado ao avaliar os conhecimentos de seu usuário e organizar a forma de apresentação da informações.
3 – A DOCUMENTAÇÃO DEVE SER PROJETADA PARA SE ADAPTAR AO FIM A QUE SE PROPÕE
4 – NO USUÁRIO, DEVE EXISTIR UMA PESSOA COM A RESPONSABILIDADE DE COORDENAR E DISSEMINAR A DOCUMENTAÇÃO.
Essa pessoa deve centralizar toda a documentação gerada, a fim de garantir que as mudanças cheguem ao local devido e que as pessoas envolvidas utilizem as instruções existentes.
Deve, também, coordenar as mudanças a serem retornadas ao documentador, através do levantamentos informais posicionado-o sobre o uso da documentação.
A afirmação acima prende-se ao foto de que toda mudança deve ser direcionada a uma pessoa. Se isso não ocorrer, o processo já começará desorganizado e o material será, invariavelmente, perdido e desordenado.
CONCLUSÃO
Ao documentador cabe controlar tudo o que será feito, através do uso das palavras, formatos, ilustrações e níveis de detalhe. Logo, é oportuno citar aqui alguns parâmetros sobre o seu perfil, pois, da sua atuação depende uma documentação a contento do usuário. Ao documentador é desejável um conhecimento teórico, com algum treinamento e experiência em processamento de dados pois para uma boa qualidade de engenharia de documentação é necessário um profissional técnico com alto nível de habilidade em escrever. É importante lembrar que documentadores técnicos não são “produzidos em casa”. Essa técnica pode parecer econômica no início, mas a documentação irá sofrer até que se encontre os candidatos certos, tornando-os experientes com o tempo. O administrador que emprega documentadores deve verificar exemplos dos seus trabalhos já executados, para poder avaliar a clareza e qualidade.
O compartilhamento das responsabilidades entre analista e documentadores é importante para produzir uma documentação de sucesso. Quem define o que é sucesso? A resposta é: o usuário.
Publicado no Journal Of Systems Manegemente em fevereiro de 1983
Traduzido por: MARIA JOSÉ RESMER – DIDOB
Condensado por : ELIANE DO ROCIO TEIXEIRA
( Stephen F. Jacobus)
Quando você fala com pessoas de processamento de dados e lê periódico referentes ao assunto é comum ouvir os mesmos tipos de questões serem repetidas.
Como eu consigo que os analistas/programadores documentem seus sistemas?
Como eu consigo que as áreas usuárias leiam as documentações que damos a eles e sigam os procedimentos?
Estas questões sempre se repetem porque elas são inadequadas e ignoram a profundidade do problema..
RESISTÊNCIA PARA PRODUZIR DOCUMENTAÇÃO:
Ao se trabalhar com pessoas de Processamento de Dados, descobre-se que:
1 – Algumas delas sentem dificuldades para escrever.
2 – Muitos técnicos não gostam de documentar seus trabalhos.
3 – Muitos técnicos são orientados para tarefas, e não para pessoas.
Considerando que os técnicos precisam acompanhar a elaboração da documentação de sistema, essa se apresenta como uma “batalha” adicional, um impedimento para terminar o projeto em tempo. Então acaba resultando um trabalho pesado. A documentação fica resumida a um agrupamento de informações, nem sempre aprofundadas, que prejudicam a sua qualidade.
As seguintes regras são importantes para assegurar uma documentação de sistemas útil e gerada em tempo hábil:
REGRAS PARA DOCUMENTAÇÃO EM PROCESSAMENTO DE DADOS:
1- Definir responsabilidade específica para desenvolvimento e liberação de documentação.
2 – Empregar documentadores experientes, ou treinar seus próprios ( e aceitar alguns atrasos).
3 – Dar autoridade aos documentadores.
4 – Insistir que os usuários sejam incluídos no desenvolvimento e revisão das documentações desde o início.
5 – Possibilitar que o pessoal de marketing reveja quaisquer documentos que irão afetar sua imagem como o cliente. Isto inclui documentos técnicos.
6 – Testar, ao mesmo tempo, a nova documentação do sistema.
7 – Desenvolver, forçar a utilização e revisar padrões de documentação.
8 – Tomar uma decisão cuidadosa a respeito da centralização ou descentralização do grupo de documentação.
9- Designar um coordenador de documentação em cada departamento, para receber documentações.
10 – Dar, ao coordenador do departamento de documentação, autoridade para periodicamente avaliar os tipos e adequação das documentações em uso, quanto à facilidade e divisões.
Também é importante destacar o cuidado que as empresas devem em desenvolver Padrões de Documentação que especifiquem o que deve ser incluído em certos tipos de documentação.
Padrões na Documentação são úteis:
* Se eles não forem muito genéricos ( tentando abranger todos os tipos de documentação).
* Se eles definirem o processo de revisão para documentação.
* Se responsabilidades de efetuar provisões nos padrões forem especificamente incluídas.
* Se responsabilidades para manter o padrão corrente tiverem sido determinadas.
* Se autoridade para impor um padrão for designada para um grupo específico.
* Se autoridade para revisar documentação, em um intervalo de seis a doze meses, for designada a um grupo específico.
Não é tarefa pequena, certo? Difícil de fazer, porque isso requer interagir com outros departamentos, envolve muita autoridade, e requer um grande comprometimento com documentação, por parte do administrador. Toma tempo e vontade de negociar.
Essa questão de negociação envolve desde a revisão de um manuscrito, passando por uma elaboração preliminar até a condução a uma revisão final, para assegurar que a documentação ainda esteja atualizada.
Inicialmente, a revisão será feita pelo chefe do documentador. As revisões posteriores serão feitas por outros departamentos e usuários. Comentários são “retornados” ao documentador que incorpora as mudanças, quando apropriadas, e contata os que revisaram para clarear as dúvidas.
Em resumo, escrita técnica requer considerável habilidade, e ainda algum tato.
Portanto, um candidato para a posição de documentador deve ser selecionado cuidadosamente e não de um grupo de trabalhadores do escritório.
DOCUMENTAÇÃO CENTRALIZADA X DESCENTRALIZADA:
A questão aqui é: deve-se ter um grupo de documentadores em cada departamento, ou criar um departamento separado (centralizado) que é independente do controle de sistemas, operação ou administração?
Não há uma resposta para todas as situações. Se existirem grupos de documentação esperados ficará difícil a qualquer um, exceto ao auditor, avaliar e controlar a qualidade da documentação. Isto é particularmente certo se as relações interdepartamentais forem difíceis.
O analista e o documentador podem intercambiar material técnico, mas mudar a documentação básica torna-se uma questão política.
De outro lado, pequenos grupos dentro de cada departamento pode resultar em um relacionamento “fraternal” com os empregados técnicos. O resultado pode ser que o fluxo de informação para e o documentador seja facilitado enormemente. Quando mais a documentação incluir os usuários no ciclo, mais facilmente as coisas sairão como eles querem. Contudo, cabe ao documentador a habilidade no relacionamento com o usuário, evitando opiniões estremadas que venham a comprometer a limitar a utilidade da documentação.
MAIS X MENOS:
Esta questão é mostrada de várias formas:
. Qual o volume adequado da documentação?
. Que vantagens são obtidas através da documentação?
. Como podemos diminuir a quantia de papéis “voando” à nossa volta?
. Como podemos ter certeza que a empresa dispõe do tipo de documentação adequada?
Essas questões diferem conforme a ocasião, representando diferentes suposições relativas à documentação. Por isso, antes de respondê-las, devemos levar em consideração os seguintes pontos:
1 – CADA NOVO SISTEMA E CADA MUDANÇA NO SISTEMA DEVEM SER DOCUMENTADOS
Em muitos casos, isso significa editar páginas de mudança e periodicamente reeditar toda a documentação.
2 – DOCUMENTAÇÃO DEVE SER EFICIENTE PARA QUE O LEITOR POSSA, RAPIDAMENTE ENCONTRAR O QUE PRECISA.
Entretanto, essa documentação também deve ser acessível o suficiente para que o leitor compreenda o conteúdo sem conhecimento prévio de um vocabulário especial. Isto significa que o documentador deve ter cuidado ao avaliar os conhecimentos de seu usuário e organizar a forma de apresentação da informações.
3 – A DOCUMENTAÇÃO DEVE SER PROJETADA PARA SE ADAPTAR AO FIM A QUE SE PROPÕE
4 – NO USUÁRIO, DEVE EXISTIR UMA PESSOA COM A RESPONSABILIDADE DE COORDENAR E DISSEMINAR A DOCUMENTAÇÃO.
Essa pessoa deve centralizar toda a documentação gerada, a fim de garantir que as mudanças cheguem ao local devido e que as pessoas envolvidas utilizem as instruções existentes.
Deve, também, coordenar as mudanças a serem retornadas ao documentador, através do levantamentos informais posicionado-o sobre o uso da documentação.
A afirmação acima prende-se ao foto de que toda mudança deve ser direcionada a uma pessoa. Se isso não ocorrer, o processo já começará desorganizado e o material será, invariavelmente, perdido e desordenado.
CONCLUSÃO
Ao documentador cabe controlar tudo o que será feito, através do uso das palavras, formatos, ilustrações e níveis de detalhe. Logo, é oportuno citar aqui alguns parâmetros sobre o seu perfil, pois, da sua atuação depende uma documentação a contento do usuário. Ao documentador é desejável um conhecimento teórico, com algum treinamento e experiência em processamento de dados pois para uma boa qualidade de engenharia de documentação é necessário um profissional técnico com alto nível de habilidade em escrever. É importante lembrar que documentadores técnicos não são “produzidos em casa”. Essa técnica pode parecer econômica no início, mas a documentação irá sofrer até que se encontre os candidatos certos, tornando-os experientes com o tempo. O administrador que emprega documentadores deve verificar exemplos dos seus trabalhos já executados, para poder avaliar a clareza e qualidade.
O compartilhamento das responsabilidades entre analista e documentadores é importante para produzir uma documentação de sucesso. Quem define o que é sucesso? A resposta é: o usuário.
Publicado no Journal Of Systems Manegemente em fevereiro de 1983
Traduzido por: MARIA JOSÉ RESMER – DIDOB
Condensado por : ELIANE DO ROCIO TEIXEIRA