Re: Please stop writing specifications that cannot be parsed/processed by software

On 5/25/2023 3:57 PM, Roger L Costello wrote:
> 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.

The requirements document was written in Word, but Hallelujah! my 
supervisor had been very diligent about using a rigid and consistent 
(and simple) format. I wrote a Python program that was able to extract 
all the info I needed and format it into an convenient XML format.  Then 
of course, I could create reports of what he had asked for using XSLT.

When the document had been modified, it was trivial to re-run everything 
and get it up to date.


_______________________________________________________________________

XML-DEV is a publicly archived, unmoderated list hosted by OASIS
to support XML implementation and development. To minimize
spam in the archives, you must subscribe before posting.

[Un]Subscribe/change address: http://www.oasis-open.org/mlmanage/
Or unsubscribe: [email protected]
subscribe: [email protected]
List archive: http://lists.xml.org/archives/xml-dev/
List Guidelines: http://www.oasis-open.org/maillists/guidelines.php