2. Introduction

Welcome to MetaFactory.io, MetaFactory’s site for Technical Documentation.

MetaFactory primarily offers services and tooling for intelligent software development. To get the most out of this tooling, you need proper documentation and in many cases proper education too. And that’s where the MetaFactory Academy comes in.

The Metafactory Academy offers several sources of information and education.

_images/MetaFactoryAcademy.02.png

  • MetaFactory.io

    This website. It offers technical documentation for a wide range of (potential) users of the MetaFactory Tool.

  • Sphinx at MetaFactory

    This documentation is generated and maintained in a Sphinx environment. With ‘Sphinx at metaFactory’ you are quickly used to and up-and-running with this remarkable documentation system.

  • The Showcase application

    An application that is especially developed for training purposes and is a rich source of examples.

  • Classroom training for the MetaFactory platform

    A complete training for working with the MetaFactory Platform and the application of the Metafactory tooling.

For more information on MetaFactory.nl please visit our webstie at MetaFactory.nl.

2.1. How this documentation is setup

A key aspect of good and functional documentation is that the information is strictly sorted in well-defined information types. An example for a car: for finding out which tire pressure is reccommended, you need completely different information than for learning how to drive safely. For the first you need technical specifications (Reference), for the second you need a course or Tutorials.

Readers with different backgrounds and levels of knowledge and experience have different information needs. The aim is that each reader quickly finds exactly the information that he or she requires.

We adopted a division into four aspects, each with its own specific focus:

_images/four-types-of-documentation.02.png

Fig. 2.2 The four types of documentation (Borrowed from ‘What Nobody tells you about documentation’ - Daniele Procida aug 2017)

  1. Tutorials: documentation that is learning-oriented. They contain lessons that take the reader by the hand though a series of steps to complete a project.

  2. How-To guides: documentation that is problem-oriented. They contain guides that take the reader through the steps of common problems.

  3. Reference: documentation that is information-oriented. It contains technical descriptions of MetaFactory concepts, like patterns, snippets, metadata, hooks.

  4. Discussions: documentation that is understanding-oriented. It contains explanations that clarify and illuminate a particular topic.

Want to know more? See the YouTube presentation What nobody tells you about documentation

2.2. Intended Audience

This documentation is intended for all (potential) users of the MetaFactory tooling.

Let’s be fair. Working with this kind of tooling is different from ordinary manually programming. At first it seems quite complicated. And yes, it requires more abstraction abilities. The real fun is that the focus moves from coding (often repeatedly the same stuff) to modeling. You are developing at a higher abstraction level. Only writing custom code for project-dependend stuff. The repetition is then done by the generation process.

To be practical we make a distiction between:

  • Newbie

    You are an experienced (say Java) developer. You are interested in Software Development Automation, but you have never worked with any SDA tool. You need to learn about SDA concepts and how they are implemented using the MetaFactory tool. So:

    Topics, especially intended for Newbies are marked with a StarN M.

  • Crack

    You are an experienced developer and have worked with one or another SDA system, but not with the MetaFactory tooling. You need to learn about specific aspects of the implementation of the MetaFactory tool. So:

    Topics, especially intended for Cracks are marked with a StarC M.

  • Pro

    You have been working with the MetaFactory tooling and know it like the back of your hand. All you need is reference information. So:

    Topics, especially intended for Pros are marked with a StarP M.

Attention

Some of the documentation is not ready for publication yet. For the time being we will publish this documentation nevertheless, although actually it’s not suitable for external users.

These topics are marked as internal: Internal L

2.3. The Showcase

MetaFactory created the Showcase application to be able to demonstrate the many aspects of Software Development Automation using the MetaFactory platform by means of an application that doesn’t require knowledge of the (business) process it supports. That’s why we created the Bookstore application.

Bookstore applicaton

Everybody knows what kind of data and processes are involved in a bookstore, so that doesn’t divert the attention from our main focus: software development.

The Bookstore offers examples for different audiences, from the manager who is interested in the business benefits of Software Development Automation, to the hard-core developer who wants to experience what meta-programming offers him (or her) in daily work. It covers the whole development track with a development, test, acceptance and production environment.

The Showcase will keep on growing and be used to develop, verify, test and approve new reusable patterns for new features, before these patterns will be used in projects. In this way we assure the quality of the new patterns and eliminate the risks of applying the patterns in active projects. A separate group of developers will perform the quality checks following a predefined protocol.

Exclam M Priorities

The Showcase application will first focus on existing patterns and metadata. After this is realized, the Showcase application can be used to create, test and document new code instructions.

3. Terminology

3.1. A Pattern is not a pattern

Hammer M MetaFactory itself is in a continuous process of development

In all software systems you can find pieces of rather generic logic that occur everywhere in your sources. These pieces are called ‘patterns’.

A MetaFactory developer recognizes these patterns. Based on that she creates code instructions which MetaFactory (the tool) uses to generate source code. In the past these code instructions were called ‘Patterns’. But actually that name is wrong because they are not patterns, but create patterns.

Nowadays we want to get rid of the misleading term and are in a transition phase in which we replace ‘pattern’ by ‘code instruction’.

The standard filename for code instructions will change from ‘pattern.xml’ to ‘codeinstruction.xml’. And the namespace changes too. Loupe S codeinstruction.xml.

Considering the vast amount of code and documentation that uses the term ‘pattern’, it will take a long time before the term really is abandoned. In the meantime please consider ‘pattern’ as a synonym for ‘code instruction’.