My team is trying to put together a microservices application whose tech stack includes Event Store. Of the entire tech stack in the application, I typically have to work the hardest to sell Event Store to other members of my development team. Part of the reason for this is a general lack of awareness of event sourcing as an architectural pattern, but I think I’ve evangelized event sourcing to the point where people are sold on it.
However, I’m finding it harder to sell people on Event Store itself, and one of the chief reasons for this is that the documentation is very very sparse, and some of the meatier bits (for example, anything about projections) are dispersed throughout old blog posts.
I really like the idea of Event Store, and I’m pleased with it so far in practice (minus a few hiccups). I’d like it to succeed, not least because we’ve already built so much around it, and planned even more.
So, speaking as a fan, and an architect who has bought in, I feel myself entitled to push on this very real pain point: it’s time for the documentation to level up until it reaches a higher plateau of completeness and maturity. What is there now is a good start, let’s say a first draft. But when you’re already at the third major version of your software, I think you need to be farther along than you are in terms of the quantity, completeness, and organization of your documentation.
EXAMPLES of stuff that’s missing
- All the stuff about projections is buried in very old blog posts. Blog post != documentation.
- In particular, we need a comprehensive projection API document. Not just a collection of how-tos.
- Also: let’s have a complete list of all the special streams generated by built-in projections. For example, the event type ( $et- ) projections. These kinds of tools are really useful but hard to discover.
- Queries: what are they? Are they the same as projections? Can you do different things with them? Is one a subset of the other?
- Guide to using the admin web portal
- Troubleshooting guides
- Lots more about clustering vs single instance
- General scalability issues
- Installation guides on other systems besides Ubuntu on Linux.
- Basic structure of an event including clear description of all the parts.
- Stream names and categories. What you can do with categories.
- More general than this: discussion of the domain model: talk about event sourcing; what is a stream? how does it work? Patterns of accessing it, etc.
- Non-functional limits of the system (i.e. how many streams allowed? How many events per stream)
- Strategies for getting around these limits if necessary
- Best practices and usage patterns
There is probably more, but that’s all I can think of at a single pass.