Automated documentation of a workspace

It is my conviction that FME is an advanced tool for managing and manipulating data streams to get the requested information at the end of the process. Due to the inexhaustible number of FME possibilities, however, it is not always clear how this information ultimately comes about. From that point of view, it is of course logical to provide more order and present an overview here.

Unfortunately, describing what is happening in a workspace is not easy and it takes a considerable amount of time to explain the transformers and the configurable behavior that they exhibit. It is therefore an additional challenge if a change has to be made to that complex process that can result in the documentation also having to be changed and the documentation already realized being revised. Very recognizable is the effect of a client's question, “Where is the documentation for the workspaces?” This is usually the time to think about it again and it often happens that it is very difficult to recall exactly the line of thought that led to the specific choices that have been made, which is precisely the information that you want to capture. It almost never says anything about the how but mainly about the why.

My starting point is therefore to make the documentation a part of the workspace and transformers, just as it is with other programming languages. That is why we use bookmarks, bookmark descriptions and annotations with explanatory text. By using these options, we can record our arguments about certain choices — and in this way, it is always possible to reproduce why we have made certain choices. By cleverly dealing with numbering in bookmarks and making use of nested bookmarks with sub-numbering, insight can be given into the route that the data follows through the workspace. In combination with a well-filled properties box, we therefore have all the input that is needed to generate an accompanying descriptive document about the workspace.

This is because output about the workspace can be generated using the FMW reader, which extracts the text, numbering and properties from the bookmarks and workspace. The information that is generated in an output file can then also be given the order that is applied in the bookmarks. In this way we automatically generate documentation associated with workspaces, which we can, for example, save and share on a wiki page. The documentation is thus available for colleagues and the system administrator. Because the documentation can be updated automatically with every change in the workspace, it is always up-to-date and therefore of good quality. The documentation is well-structured on the basis of automated documentation and is therefore also easy to consult and interpret. The documentation system is easy to reuse, easy to maintain and easily exchangeable with other FME users.

This primitive workspace shows just a fraction of the possibilities. The result is below:

1. The reader reads all bookmarks from the selected workspace
2. Here the sequence numbers and text are taken from the bookmarks
3. Sort the bookmarks in a list based on the sequence number
4. Combine all texts from the list of bookmarks into one attribute
5. Write the text to a file