One of definitions of engineering is “The action of working artfully to bring something about.” Bringing something of value about is usually quite a lot of effort. In a situation of limited resources, which is the case most of the time, that efforts need to be carefully organized to achieve the maximum bang for the buck.
The goal of Nasdanika Engineering is to help to carefully organize efforts in order to bring something about. That “about” may be a software product, an organization, a vacation, or life in general.
Nasdanika Engineering provides science and tooling to guide and track the process of translating dreams and ideas into organizing thought, sharing that organized thought with others and aligning efforts of many to turn dreams and ideas into reality.
Shall YAML and Markdown sound scary for non-technical people, YAML is a glorified indented list - if you know how to create a PowerPoint slide with bullet points, you should be able to manage YAML. And Markdown is pretty close to plain text.
YAML and Markdown are resource formats supported out-of-the box. If needed, model data can be loaded from other resources. E.g. issues can be loaded from issue trackers such as GitHub Issues, Jira, or MantisBT by implementing resource factories for respective systems.
You wouldn’t need a database or a cloud application - you can keep your plans on an encrypted flash drive in a safe in an underground vault, shall they be super-secret.
Because with Nasdanika Engineering all artifacts “live” in one place it makes it an attractive choice for small efforts, or efforts which may have long periods of dormancy - POC’s, R&D, ideation, innovation, and conceptualization. In the case of innovation in an organization, innovators may benefit from shared models, e.g. an organization model with products, services, personas, and goals - in this case an innovation idea can be defined in terms/context of these products, services, and goals. E.g. “Build a new service X which would leverage an existing service A and product B to address goal C of the internal persona D”. This disciplined innovation would help the innovators to align their innovations to organization goals, and the rest of organization to grasp the value of the ideas and prioritize them for implementation.
In a team environment Nasdanika Engineering files can be kept in a source control system such as Git. For example, on GitHub. In this case site generation and publishing can be done on code push, e.g. with CircleCI or Jenkins.
In case of using Nasdanika Engineering to engineer a software product, engineering files with the source code. In a multi-module, multi-product scenario engineering files for each product/module can be kept with the source code of that product/module and then be federated into one model to generate a team/organization site. Nasdanika documentation site is generated this way.
Nasdanika Engineering has 46 classes - see below and in the navigation panel on the left, which can be roughly grouped into the following categories:
It is not necessary to know and use all the classes at once - pick what you need to get started and then expand as needed.
The below sections provide overview of the core concepts, each of the categories, and explain how to get started with Nasdanika Engineering. For step-by-step instructions see the User Guide.
If you clone, you may checkout any of tags as a starting point.
With Nasdanika Engineering you create an engineering model by defining instances of model classes in YAML or other format, e.g. JSON. YAML is a preferred format because it is more user friendly and also because Nasdanika Engineerings keeps track of line numbers in YAML files, but this functionality is not currently supported for JSON. As has been mentioned above, a model can be loaded from different types of resources, e.g. some parts of the model can be loaded from YAML while other parts would be loaded from, say, Jira.
When creating YAML specifications use “Load specification” section of respective classes to find supported configuration keys.
Below is a partial sample definition of an organization:
engineering-organization: name: Nasdanika Engineering Demo path: demo table-of-contents: role: content-left header: Contents
You can find a full definition here.
Note that the organization definition starts with
engineering is a package name and
organization is class name. For references which are not
homogenous it is required to provide class names. Homogenous references have elements of the same type and therefore there is no need to provide class names.
table-of-contents above is an example of a homogenous reference.
A YAML file can reference another YAML file by using a string as reference value, unless that reference is a
strict-containment. In the latter case the value is treated as a value of the default feature, as in the case of Transition:
elements: - engineering-activity: name: A path: a outputs: - b
outputs is a journey element homogenous reference with strict containment and
target is Transition’s default feature. Therefore,
b is treated as a value of
Default features are shown in bold in load specifications.
The below code snippet demonstrates referencing specification defined in other files/URL’s:
resources: - resources/user-guide/root.yml - resources/base-journey/root.yml - resources/extended-journey/root.yml
resources reference is not
strict-containment and therefore its value is treated as a URL, which is resolved relatively to the YAML resource URL. Please note that when referencing external resources
homogenous is ignored, i.e. the resource must contain the type declaration.
The generation process creates a lot of console output, you may redirect it to a file if desired.
The generation process diagnoses the model and outputs warnings and errors, if there are any, at the end of console output. Warnings and errors are also displayed on the generated site. Diagnostic output to the console is very detailed and may be hard to read. It is easier to use the generated site to inspect the diagnostic, unless there was
FAIL level diagnostic which caused generation to fail.
Generation may also fail due to incorrect configuration - wrong configuration key or resource URL. Inspect error messages for details. Below is a sample error message - it tells what is wrong (Unsupported configuration key) and the location of the offending specification (demo.yml line 3 column 4):
Tests in error: testGenerateDemoSite(org.nasdanika.engineering.demo.TestModel): Unsupported configuration key: path_ at file:/.../engineering-demo/target/test-classes/demo.yml 3:4
This section provides an overview of models classes which can be categorized as structural - instances of these classes define a skeleton to which other instances are “attached”.
First of all, ModelElement and NamedElement are base classes from which most of the other classes inherit. Although is some cases not necessary, it is recommended to specify
path attribute for model elements in order to have semantic URI’s and URL’s.
A number of classes inherit from Period which supports floating, absolute, or relative start and end dates - temporals, and duration. It allows to express plans in relative temporal terms, e.g. “Hire a tester 60 day after the project kick-off” where “Project kick-off” is an event which can be initially “unbound”, i.e. specified without absolute or relative date. Later on an event can be “bound” to an “instant” - absolute time, or to another temporal - an event or start/end of a period, e.g. 30 days before quarter end. Temporals may have lower and upper bounds. For example, an exact date for some event may be unknown, but it might be know that it would happen no later or no sooner than a certain point of time - absolute or relative - or within a certain time range.
Engineer or Organization are typically roots of the model. For a single-person efforts with no delegation whatsoever you may define a model with an engineer as its root. However, in many cases even for efforts which start as one-man shop eventually comes time when some tasks need to be delegated and execution tracked. This is when you’d need an organization as it is an engineer which can contain other engineers.
Engineers may contain modules and products and own engineered elements. Note that an Engineer is a sub-class of EngineeredElement, i.e. an Engineer can be engineered. For example, a person can be mentored or take courses and an organization can improve its processes.
Behavior classes are used to represent things to be done on the structure or external entities to achieve goals. They are subdivided into two sub-categories:
There are two base classes for the classes in this category:
In your models you would use subclasses of the above two classes:
The How means what is traditionally User Guides and Cookbooks - step-by-step instructions. With Nasdanika Engineering you can create such step-by-step guides as documents with multiple sections.
However, there is another way and you may choose what is most appropriate in a given situation and even combine the two.
Humans are image processors, not text processors. So if your instructions are not single level linear, i.e. there are steps and sub-steps and also conditional logic, chances are that if presented visually these instructions would be easier to follow.
Nasdanika Engineering has a number of classes which can be used to create visual representations of (work)flows. Because they can be used to capture scenarios of how personas use products and services provided by an engineer or an organization, they are called journeys.
Because journey elements inherit from ModelElement, they can have documentation sections to benefit from a combination of non-linear and linear knowledge representation.
One important feature of journeys is journey inheritance, which is similar to inheritance in languages like Java - it is possible to define a base journey and then extend it and customize (override) journey elements.
Journey inheritance can be useful in hierarchies such as organization hierarchies and technology hierarchies.
In an organization hierarchy higher levels can define generic processes and specify which elements can be customized at lower levels and which cannot. Lower levels of the organization would customize what they need to their specifics, e.g. local regulations.
Similar to that, in the world of technology one can define, say, a generic journey explaining how to develop and deploy a microservice. Then that journey can be customized to different ways to deploy, e.g. different cloud providers - private and public, and their offerings.
Document and section inheritance is not currently supported, it will be added in the future releases.
Anything worthwhile takes time and effort to build, … and there are so many ways to skin a cat. If you are working on that worthwhile alone you will need a way to ensure that you are staying focused on achieving your goals. If you are working with others, you’ll need a way to provide to your team means for efficient decision making to avoid prolonged debates.
An issue “Build Customer Profile microservice” can be aligned to a customer persona goal “Manage my information” and The Twelve Factor App principles.
Nasdanika Engineering also supports the OKR goal setting framework via Objective and KeyResult classes. It is possible to define issues as initiatives under key results. This provides an alternative way to organize efforts - instead of defining issues under products and modules and then aligning them to aims. You may pick a method which works best for your situation or use a combination of these two approaches.
In the case of defining issues as initiatives you may have something like this:
Appearance and its subclasses can be used to declaratively customize the generated UI. Customization can be done at the class level, i.e. customizations would apply to all, say, issues, or at an individual model element level.
Model elements and documents which use sections can use tables of contents.
Engineered elements can have discussion topics with messages and nested forums. For example, there might be a discussion forum for a document section or for a journey activity. This allows to have highly focused micro-communities of practice where engineered element owners and experts help others.
“As-code” approach may be attractive in the following situations: