I was looking into documenting the existing Elixir code generators.

While looking around I found the following: https://github.com/pragdave/mix_generator

This is a project by Pragmatic Dave that helps generate generators!

A few years ago I was finding myself annoyed by the lack of documentation at work. At the time I just complained and carried on. This raised my stress level and did not help anything.

I then decided to be the change that I wanted, and started writing documentation for things that I needed. Once you have a start you can ask questions and will find that others will help expand.

This applies beyond documentation. If I find something wrong that is put down to “that violates our policy” then I ask to see the policy in writing. It’s very common for there to be talk of a policy that does not exist.

If something is wrong or annoying you try to see what can be changed, how can you help to make this happen. Sometimes this just a case of getting the right people to talk to each other.

Back in 2012 in the Open Source Journal (2012 issue 4) Robert C Martin argued that the database in not the center of your application. Given that DDD is more prevent now than then I would like to make a further argument.

The main problem that some companies have in building a domain model is that they don’t understand the difference between their user interface and the model. This is a key point. For some applications these can be very similar. However for others there are processes that live beyond the UI that are not typically discussed outside of the development team. It’s this part that having a clear distinct Domain Model helps with.

In a recent presentation I was demonstrating a new proposed architecture. Part of the demo included workflows using the architecture based upon some documentation that the customer was familiar with.

I received feedback that this was effective.

To generalise this when introducing something new to someone try to link it to something that they already know.

Elixir does not have global variables.
This can make certain operations difficult.

This is where an Agent helps:

{:ok, pid} = Agent.start(fn -> 42 end)
pid |> Agent.get( & &1)
pid |> Agent.update(&(&1 + 1))
pid |> Agent.get( & &1)

This wtaps some state in a Process.

Since it is only updated via messages some concurrency issues are removed,
Privacy is achieved by keeping the pid hidden.

Note that the simple update has a 5 second timeout. The update will fail if it takes too long.

Over the last month I have been using C4 PlantUML extensively to design a system.

PlanrUML is a set of tools that can be used to generate UML diagrams. In particular I have been using the C4 Model combined with Activity diagrams.

These can be used to generate diagrams that can be included in the github project and referenced from the README,md file.

Both vscode and intellij have decent plugins that can allow for rapid previews.

You can keep multiple diagrams source in a single file which helps to keep them synchronized in version control.