Logicdoc is an optional ABL component that enables you to
- document your business logic in business terms, providing transparency to Business Users. This improves IT / Business User communication, which can reduce project risk
- provide traceability from requirements to logic so Developers can maintain logic based on an understanding of why existing logic was defined
Logicdoc is an extension of Javadoc, used as summarized below:
- You define classes that represent Use Cases (designated by the
@UseCase annotation). Such classes may or may not contain executable code
- You define methods that represent Requirements (designated by the
@Requirement annotation). Use normal javadoc to explain the requirement
- You define
@see tags to as part of the method (Requirement) javadoc to designate the Logic Methods that implement the requirement
- You run a ABL-supplied ant script which executes the javadoc extensions resulting in Business User readable documentation as shown below
Please review the Architecture
before reading this document.
|Here is a Logicdoc page for a Use Case Class, that is, a class with the @UseCase annotation. In this example, we are documenting the Use Case
This class need not be executable. Or, you might wish to define Logicdoc in your existing classes, e.g., jUnit test classes.
Note that the word "Class" has been replaced with "Use Case", and that "Method Summary" has been replaced with "Requirement Summary". This makes the logicdoc elements of your javadoc more readable by Business Users.
As noted above, you define the Requirements as Methods with an @Requirement annotation. So, we see that we have requirements like check credit, create line item usage forms and so forth. These are detailed below. Per the usual javadoc convention, the first sentence is retained in this summary list.
- You can put Logicdoc classes in any package you wish. You may wish to employ conventions, such as defining packages representing Business Processes.
- Per the Rational Unified Process (TM), the list of Use Cases is valuable input to the Project Plan. It defines (all of) what we are building: the system is the sum of the Use Cases.
- By the same token, the Use Case is the sum of the Requirements. These Use Case / Requirement lists can form the backbone of the "contract" between IT and Business Users.
This portion of the page shows the requirement detail.
Use normal javadoc notation to capture the understanding of the requirement, reflecting perhaps the result of a design session with Business Users.
The Requirement to Logic Tracing section is derived from
@see javadoc entries referencing the Logic Methods used to implement the requirement.
Note: unlike normal @see references that merely show the name of the referenced method, here we show the first sentence of the Logic Method's javadoc. This is valuable so you don't have to click the link to see the rule, losing your visual context on the other rules for the requirement.
Projects are continually faced with the following:
- Requirements Risk
- A leading cause of project failure is vague or changing
requirements that serve the needs of Business Users, Developers, and the
Analysts who mediate between them.
- Too many projects produce little or no documentation. Business Users cannot determine what the system does, and IT incurs increasing costs and risks during maintenance.
- Documentation Drift
Even when documentation is produced, it often "drifts" away from the evolving implementation, sometimes with the result that it is so misleading as to be worse than no documentation at all.
Business Logic - since it is stated in Business terms but is also executable,
offers an opportunity to strengthen the critical collaboration between
Business Users and IT. The approach described here leverages this
unique opportunity, in the context of some well-accepted tools:
- Rational Unified Process (TM)
- Whether used formally or informally, the notion of defining a
system in terms of its Business Processes (Work Flows) and Use Cases is
- Javadoc: in-project documentation
- A core premise of Javadoc is that documentation outside the
project is rarely maintained, and tends to drift away from the
What is Logicdoc
Logicdoc is an extension of Java/Groovydoc which you can see it here. Elements of that site were used in the Place Order description, which can peruse to see selected screen shots, and to get an overview of using Logicdoc.
Specific extensions made to Java/Groovydoc include:
Logicdoc is based on two useful packages:
- UMLGraph TM provides services to build UML diagrams from annotated Javadoc. See examples here.
- Enhanced Groovy Doc provides services to invoke nested Doclets
Business-user friendly terminology
While much of Logicdoc output is for Developers (class diagrams, etc), Use Case Class elements that document the Requirements are directly relevant to Business Users. Logicdoc therefore alters the terms, e.g.:
- Use Case (not Class)
- Requirement (not Method)
Rule References converted to rule summary
Referring to the diagram at the top of this page, note the "Requirements to Logic" list. Developers define this list with @see entries, with references to Business Logic Component Rule Methods. For example:
Instead of the usual Javadoc conversion of this term into a hyperlink, Logicdoc uses the text of the target rule. This enables you to read the list of rules in one glance, rather than having to click a hyperlink to see the name and definition of each rule:
fail if Balance > CreditLimit
Why use Logicdoc
Though totally optional, Logicdoc can contribute to the success of your project.
Explicit Requirements Capture
Requirements Risk is a well-known challenge, which can manifest as vague requirements, or "requirements creep". Logicdoc can help by providing an explicit enumeration of requirements:
- Can help get Business Users and IT in sync
- Can help reduce the risk Requirements Creep
- Can assist in building the Project Plan -
Use Cases and Requirements are schedule able items
Maintenance agility and costs benefit greatly when the requirements are clear (both old and new), and there is clear trace ability from Requirements to implementation. As shown at the top of this page, Logicdoc can:
- Improve quality by making designs more transparent
Business Users can review the logic to be sure it is correct and complete
- Reduce Maintenance costs and risk by clarifying requirements intent and design approach
Diagrams enable Developers to clearly visualize system contents and operation. Such clarity further increases agility and reduces costs.
Who uses Logicdoc
While Logicdoc is maintained primarily by Developers and Analysts, many other team members can benefit:
- Project Managers can gain confidence that the Project Plan and Requirements are in sync
Project Managers may wish to build project schedules that utilize the Use Case / Requirement information. You may wish to investigate Eclipse support for tasks that can integrate these with your project management software.
- Business Users benefit from transparency
- Without Business Logic Automation, Business Users must ask IT
to confirm system operation ("how do we calculate benefits?"), often
requiring additional IT Staff. Logicdoc enables Business Users to see
the requirements, and the actual logic that implements them
- Systems Integrators / Package Providers
Have a clean way to
deliver systems documentation that can be maintained over maintenance
How is Logicdoc used
Since Business Logic is specified in Java/Groovy Logic Methods,
normal use of Java/Groovydoc generates documentation for Domain Objects
and Business Logic Components. You will, of course, get UMLGraphs for your domain packages.
To capture Requirements and their logic
Traceability, create documentation-only Use Case Classes and Requirement Methods as described in LogicDoc Operations.
For more in mapping Logicdoc your own process / terminology, click here
When is Logicdoc used
It is your option when to use Logicdoc:
- Use Logicdoc to document the Processes and Use Cases, for scoping and communication
- Design and Implementation
- Use Logicdoc to detail the Requirements, and the Logic that implements them
- Use this information for Design Reviews
- Even if minimal/no documentation has been captured, add it
during Maintenance to document the design intent (requirement) and
implementation (Requirements Traceability into Logic)