Re: [xml-dev] Please stop writing specifications that cannot beparsed/processed by software
Dear Specification Writer,
Please stop writing specifications that cannot be parsed/processed by software. Please stop formatting your specifications as Word and PDF. Instead, use a format that is amenable to machine processing. The XML format is ideal. We want to analyze your specifications. We don't want to spend dozens of hours screen-scraping your Word/PDF documents.
If you simply must persist in writing Word/PDF documents, then please write in a consistent way so that we can screen-scrape without having to write special case code. To illustrate, in one of your specifications you provide a bunch of tables with data; each table has many rows. In some tables you reference a note. Here's a row with a note reference:
119 Approach Route (1) Note 1 5.7
Here's another row with a note reference:
52 SID Ident (1) (Note 1) 5.78
Why did you embed Note 1 within parentheses in the second case but not the first? That's an example of not being consistent. Such inconsistencies make it difficult to do screen-scraping. Please be consistent. If at all possible, write a parser to parse the data that you embed in your specification. This will immediately inform you of any inconsistencies.
Thank you,
From the people who must read, understand, and analyze your specifications
I once was asked by my supervisor to extract from a requirements
document the test/demonstration methods that were specified for
verifying each requirement. This was a long, complicated requirements
document for an orbiting satellite. The supervisor was still in the
process of writing the first draft of the document but it was pretty
well along.
