Time to level up on documentation

EventStoreDB
#1

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.
#2

" (for example, anything about projections)"

Projections are being released in 4.0 which is when they will get
documentation associated with them.

#3

That’s really good to know. Projections are an indispensable feature of Event Store, beta or not.

I’m trying to make a more general point, however.

#4

We would love to see some documentation on the internals of the .net client library. That’s something our devs are having a hard time grokking.

#5

Example?

#6

As a baseline, how about full API documentation, in the style of MSDN? You can put the documentation inline in the code and there are plenty of tools to generate the HTML documents out of that.

#7

https://github.com/EventStore/EventStore/blob/release-v4.0.0/src/EventStore.ClientAPI/IEventStoreConnection.cs#L22
every public method in the client api already has XML docs on it (its
also set to treat any missing entry on a public entry as a compiler
error). It might be worth generating these and putting them on the
site as well intellisense etc though.

The reason I asked for an example is Fredrik mentioned the *internals*
of the API. I'm not quite sure what documentation people would want on
the internal implementation.

#8

I’m not sure what he meant about “internals” either. But yeah, if you have the API docs, why not publish them on docs.geteventstore.com? Please do!

I can’t speak for Fredrik, but in addition to the baseline of API docs for the .NET client, any number of how-to pages including detailed code samples would be terrific as well. You have the beginnings of this already in the documentation, but I think it could benefit from a little reorganization. I would recommend breaking up what’s there into smaller documents, each with a more focused purpose, and use real code samples instead of just something like:

Deleting a Persistent Subscription

Task DeletePersistentSubscriptionAsync(string stream, string groupName, UserCredentials userCredentials = null);

Something else I thought of:

  • A page listing known clients of Event Store (such as the Node.js client event-store-client) - even if your company did not write them.
#9

This very forum (as well as others, such as the Github forum) can be a rich source of ideas for documentation. This one that just came in for example: how to use the client to write a linked event. A very straightforward question, with a very clear answer.

#10

great post from Zach - I completely agree.

fwiw here is my feedback sent 6 weeks ago in response to the Event Store customer reach out - you’ll see much the same points being made.

#11

By documentation of the internals I meant a simple model that can account for e.g. these settings:

MaxConcurrentItems

KeepReconnecting()

KeepRetrying()

LimitRetriesForOperationTo

LimitAttemptsForOperationTo

It should also help people understand the guarantees that the library gives and what responsibilities are on the developer.

E.g. is write order preserved and what settings are relevant for write order.

Maybe something like a diagram of a queue with relevant explanations…

#12

OK That makes sense and sounds useful.

#13

Maybe a bit of weird question.

But is there something we could do to help?

#14

Might be useful to make up a list of documentation then we can start
tagging them with "up for grabs". Github issues work well for this.

In terms of projections documentation that will be included with the
release of 4.0