Document your ANTLR grammar and parsers

Grammars and languages are good investments which can provide returns for decades. We see that routinely with our clients.
However, if something is going to be valuable 5, 10, or 30 years from now, you will need to be able to maintain and evolve it over time.
You can ensure this by building the right documentation for it.
We have a specific tool to document ANTLR grammars and a methodology to write such documentation.

What happens after you got a grammar built?

We routinely work with clients which have been using some language processing tool for 10, 20 or 30 years, sometimes even longer.

For example:

• A company which built a DSL as an evolution of Basic, and used it for over 30 years
• A company which acquired another company, owning a product based on several ANTLR2 grammars, written around 15 years before
• A company which had built pre-processors for RPG and used them for over 20 years
• A company which had built a macro-language around COBOL and used it for 20 years

All these companies were getting a lot of value from their investments on these tools and they got it for a very long time.

So what is the problem?

The problem is that often the underlying grammars are very difficult to understand, so the company have this piece of software which is important but no one is able to maintain it, let alone evolve it to fit new needs.

So they get value out of these tools but not nearly as much as they coul, if they were able to evolve these pieces of software.

Now, this is a problem due to the success of those grammars: they have been an investment providing benefits much longer after the company has lost the competencies used to build those languages. The fact is that those grammars were never documented, so for someone to familiarize with those grammars would require a significative investment.

You know how this happen, at some point the software was built, a first version was delivered. Then a few change requests followed and the original authors of the tool implemented a solution. Then time passed, the authors left the company, and the software slowly evolved in that arcane piece of technology that had always been around. At the beginning someone was brave enough to dive into the source code for doing some minor changes but as time passed this became this untouchable piece of legacy code which is too costly to evolve. It is still useful and you would like to do a list a few tweaks to it but… it is just that no one understands the grammar. It was never documented.

You can make this language tool much more valuable over time

If your language tool was able to respond to your needs as they appear, it would give you more possibility to react to changes and it would provide much more value over time.
It would also give you more predictability, as you would still have the possibility to do a fix to your grammar quickly and easily, instead of having to dive in a cryptic piece of code.

We can make it much easier to maintain and evolve these strategic tools by documenting them properly.

For doing that we have built a specific tool, and we have an approach to use it methodically. The result is that you would get a documentation, delivered as HTML and PDF, which you can keep together with the source of your language processing tools. When the time comes, in which you need to put your hands on such tool, you will be able to do it.
As an additional benefit, this documentation could help whoever need to do integrations with your grammars. For example to attach code generators to it. Or perhaps to build editors for it.

Why to document?

We think it is important to protect your investment and ensure you will be able to maintain the grammar.

You may need to change the grammar or the parser:

• To support an evolution of the grammar, for example parsing a new version of the language
• To build integrations with other tools, maybe you want to attach code generators or editors to your tool
• Because of changes in the existing integrations

These needs can come up 6 months from now, or 6 years from now. When the time comes your language tool could have became very important for your business, and when that happens you want to be able to maintain, not regarding it as this magic piece of legacy code that works and no one dare to touch.

As consultants we believe it is our responsibility to put you in the best position to maintain the grammar yourself, or delegate the maintenance to someone else. If you have the tools to understand the grammar you will have more choices at your disposal when the time to evolve the grammar comes.

Benefits

How it works

The way it works is simple:

• You deliver the grammar to us
• You deliver to us examples of code that you find representative
• We organize a meeting so that you can present us the goal of the language and how you use it
• We write the documentation
• We can possibly about questions about the way you use the language
• We deliver the documentation to you, as HTML and as PDF
• We remain available to answer any question on the documentation for 30 days

Offer

There are two possibilities to buy the ANTLR Grammar Documentation.