-
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)
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()
Targeted documentation follows a strict layout.
This section describes a typical layout
Identification table
Title : |
Documentation automation roadmap description |
||
Date: |
2017/12/19 |
Issue: |
0.2 |
Reference: |
|||
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 |
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 |
Consortium name and logo |
The fouth page MUST have a Documents section. This section consusts of two mandatory tables
-
Applicable Documents
-
Reference Documents
AD | Title/Author | Ref. | Issue |
---|---|---|---|
Date |
1 |
CCTP Convention CNES/INSU N°9999999 Phases B2 & C1 |
FOO-MG-SOW-156-CNES |
RD | Title/Author | Ref. | Issue |
---|---|---|---|
Date |
1 |
CCTP Convention CNES/INSU N°9999999 Phases B2 & C1 |
FOO-MG-SOW-156-CNES |
-
Take a look at https://github.com/Open-MBEE/docbookgen