marcdexet-cnrs / docautomation

Documentation automation

Docautomation

Table of Contents

• Goals
• Vision
• Description of the targeted documentation
  • On the first page
  • On each page
    • HEADER
    • FOOTER
  • On the second page
  • On the third page
  • On the fourth page
  • On the fith page
• Tools
• Reference

Goals

• To produce set of documentation following Quality Standards

• To limit the burden of gathering information without added value

• To manage and configure documentation as code

• To not repeat yoursef (DRY)

Vision

A engineer has no added value into fighting with que quality process. We have to help her. A lot of the burden is due to various tasks and concern that could be automatable.

• build an exact reference for the document according to a pattern

• update version number

• include exact reference from applicable documents

• check the last version of applicable documents

• check if the worklow has been followed

As described in Description of the targeted documentation, there’s a fixed layout that can be filled using automation.

doc = Doc()
doc.description = generate_description_from()
doc.build_identification_table()
doc.build_diffusion_table()
doc.build_table_of_change()
doc.process()
file = doc.generate()

Description of the targeted documentation

Targeted documentation follows a strict layout.

This section describes a typical layout

On the first page

Identification table

Title :	Documentation automation roadmap description
Date:	2017/12/19	Issue:	0.2
Reference:	ACME-FOO-SDD-0018
Custodian:	John Doe

Table of workflow

Proposed by	Role	Date	Signature
Jane Doe	Quality Leader Foo Bar ACME	2017/01/01
Contributors	Role	Date	Signature
Jane Doe	Quality Leader	2017/01/01
John Doe	Quality Leader	2017/01/01
Jane Doe	Quality Leader	2017/01/01
Authorised by	Role	Date	Signature
Jane Doe	Quality Leader	2017/01/01
Agreed by	Role	Date	Signature
Jane Doe	Quality Leader	2017/01/01
Approved by	Role	Date	Signature
Jane Doe	Quality Leader	2017/01/01

Table Of Change

Issue	Date	Pages	Description of changes	Comments
Draft 0.1	17/07/12	all	First draft
Issue 1	17/08/12	12	Includes M. Foo comments
Issue 2	17/06/13	1-5	John Doe replaces Foo Bar
Issue 2.1	18/11/13	1	Jane Doe added
Issue 2.2	18/02/15	8	FOO ACME leader updated
Issue 2.3	18/06/15	all	Upgrade to FOO-ACME-Design rules

On each page

HEADER

Each page MUST have a header that consists of a table with three parts

• on left: organisation logos

• on center: Title

• on right

  • document identification (i.e. reference),

  • version

  • date

  • current page number over the total page number (i.e. page: X/last_page_number )

Agency name and logo	Very long title acme foo bar	Reference: FOO-ACME-A-0021 Version: 0.2 Date: 17/12/19 Page: 1 of 8
Consortium name and logo

FOOTER

each page MUST have a legal notice as footer

On the second page

Second page MUST have a table of content

On the third page

The third page MUST have section about Purpose and scope of the document

On the fourth page

The fouth page MUST have a Documents section. This section consusts of two mandatory tables

• Applicable Documents

• Reference Documents

Table 1. Applicable documents

AD	Title/Author	Ref.	Issue
Date	1	CCTP Convention CNES/INSU N°9999999 Phases B2 & C1	FOO-MG-SOW-156-CNES

Table 2. Reference documents

RD	Title/Author	Ref.	Issue
Date	1	CCTP Convention CNES/INSU N°9999999 Phases B2 & C1	FOO-MG-SOW-156-CNES

On the fith page

The 5th page MUST have a list of Acronyms and abbreviations

KEY	Long description of the acronym

Tools

• pandoc

• dblatex

• docbook

• XSL-FO

Reference

• Take a look at https://github.com/Open-MBEE/docbookgen