This is an informal announcement of the first public release of the open source Adj framework.
One significant feature is “relative constraints”.
The original purpose of the Adj framework has been to facilitate creation and long-term maintenance of system diagrams. Adj has been designed specifically for diagrams of large complexity. Because of its general nature, other uses may be possible.
There has been working code for some time and there is a user guide.
You could be using it. The only file you really need is adj.js. Free of charge, forever.
You could improve on it, if so inclined.
This announcement is intended
- for SVG coding aficionados,
- for people wanting or needing to agilely maintain system drawings (schematic diagrams),
- for anyone who really wants to know, and
- for associates who knew this was under development.
Before pushing to a broader audience, however, we should
- add more intricate visual examples,
- produce one or several video clips demonstrating ease of use,
Regardless of any intended audience, this is a public post.
What it is
What exists now:
- It enforces a number of parameterizable constraints for SVG graphics elements.
- There is a working engine that processes SVG.
- It is possible to have a tolerable workflow.
- Once processed an SVG document with Adj is a usable SVG document even without Adj.
What is true
but and by now has not been demonstrated yet:
- Adj is extensible by additional algorithms.
- Coding of additional algorithms should be possible more easily after Adj’s workings have been illustrated, using Adj’s own capabilities.
Customization and maintenance of schematic diagrams
SVG and SVG with Adj documents can be generated and manipulated by software: They are XML. Hence schematic diagrams could be automatically, semiautomatically, or manually
- customized per client,
- customized per installation,
- adapted as changes occur in time.
- make diagrams from scripts
- update diagrams from scripts, e.g. add an additional server to a cluster
- automatic adaption to changing size of contents
- e.g. automatic adaption if length of text changing, or if font size different, or if additional items added to a list
- what adapts is e.g. enclosing (containing) object, or connecting line or arrow, or label on connecting line or arrow
- propagate different looks via CSS, or via scripts processing XML, e.g. XSL
What that means is sets of diagrams can be kept attractive looking for a longer time with less effort. Will such quantitative difference cause a qualitative difference? Ease of maintenance should facilitate what otherwise wouldn’t be done, would be neglected, would lead to lack of interest.
Why the Adj framework
Future announcements may explain Adj in terms and concepts devoid of my personal motivation in starting it. This time, however, you will find a few sentences with a tell-tale sign of self-centeredness, starting with the word “I”:
- I want significantly more detailed illustrations of systems. For work. Stuff that doesn’t fit into a PowerPoint slide, that doesn’t fit into the all too common illustration size half of a book page or a third of a page of a letter (A4) size PDF.
- I am painfully aware of issues of maintenance of illustrations: Names change. Items get added. Conventions change. Updating hundreds of illustrations doesn’t get done. Outdated becomes normal.
- Details, nuances, and liveliness of whiteboard diagrams don’t make it from meeting rooms into formal drawings part of generally useable documentation.
- I would have used an established or any existing tool, if any had existed or had been known to me. I was willing to use proprietary drawing tools. I have paid for Adobe softwares. I was looking at Autodesk products. I was searching without prejudice. There wasn’t a good solution to be found at any price.
Many systems I wanted illustrated so far have been software systems. Enterprise software and other kinds of software. Hopefully there will be an opportunity to publish good examples.
What has been important to me:
- recursion (many levels of containment)
- reuse of a detailed drawing as part of another drawing, e.g. if one drawing explains registers in a CPU then a system drawing could contain that detail
- ability to modify styles across any size set of illustrations (hundreds if not more), i.e. rapidly, essentially automatically
- automatic adaption to insertions, e.g. add another instance in a list, or add explanatory details
- automatic adaption to deletions, e.g. remove detail which isn’t needed in a different context
- automatic adaption to changes of size (e.g. changes of names or different font dimensions)
- maybe ability to hyperlink
- maybe ability to animate