Your documentation is the worst I've ever seen

[Scholar01]

Your documentation is the worst I've ever seen

[sfmskywalker]

I’m sorry to hear that, but I appreciate the honest feedback. Would you mind sharing what specifically makes it bad and what might make it better?

[nkosi23]

I have to say that I agree with the original poster and this state of affairs is very frustrating. As someone interested in using elsa to define workflows from code and nothing else for now (while believing that the visual designer could become handy at some point), the only thing the documentation has to cover this use case is a Quickstart page having a Hello World example.

Then the next page sort of explains how to set up an elsa web server using ASP.NET Core (but what about the: "workflow engine for ALL .net standard application" promise you made in the headline?). And then all the other pages of the documentation assume that the reader is using the elsa dashboard! And to make things worse, they also assume that we are running some docker container, so they do not bother explaining the environment the feature being documented is supposed to run on. How are we supposed to develop the confidence required to run elsa in production if even the documentation is too lazy to document the setup of the examples and of the various moving parts?

This is a complete fiasco for someone not being familiar with this project, and/or being new to Workflow Engines. I have to agree that this is the worst documentation I've ever seen on my side as well.

You should create one dedicated documentation website for every component (elsa core, elsa dashboard etc...), and stop relying on docker containers for your docs as throwing a container in basically means: we haven't figured out a clear and easy way to get people up speed with a proper written documentation. If a docker container is the easiest way to introduce people to your project, this is a red flag and an indicator that you have documentation debt.

Docker may be useful for a quick start guide IN THE PRESENCE of a properly written reference documentation for people wanting to dig into the specifics. However, it feels like the ability to hand over a container made your project lose sight of the need to invest in figuring out a proper way to document its large feature surface.

your current approach of mixing all docs in a half-baked manner is confusing, frustrating and comes across as laziness. Some projects do not have any documentation but are not that frustrating, here for some reason when I read your documentation I feel offended, you almost make me feel like you are showing me the finger. And this is even more frustrating when one can sense that elsa could have been a good fit for their project, if only the documentation of the API was a minimum decent.

Maybe your doc is somehow usable for someone being mainly interested in elsa for its visual designer capabilities. But it is utterly unusable and unhelpful for someone approaching the project with a code-first mindset I'm afraid.

[sfmskywalker]

Thank you @nkosi23 for taking the time to elaborate. Although I very much enjoyed writing the documentation we have so far, it's valuable to understand where it lacks and how it can be done better and perhaps differently. I will take your feedback to heart with future updates.

[nkosi23]

Thank you @nkosi23 for taking the time to elaborate. Although I very much enjoyed writing the documentation we have so far, it's valuable to understand where it lacks and how it can be done better and perhaps differently. I will take your feedback to heart with future updates.

Thank you for your understanding and for your work, if I finally manage to wrap my head around elsa-core and get up to speed with it (and I am not required to settle on an other solution because of the time constraints I have), I will definitely look into contributing documentation.

[sfmskywalker]

That would be fantastic. In the meantime, perhaps the console samples can shed some light on certain use cases.

Also, please feel free to ask any questions you have here and on the Elsa Workflows Discord server.

[chrisbecke]

the negativity here is a bit much, but ngl, the docs are pretty bad:

• aspnet core 6 apps don't generate a Startup.cs anymore, so pretty much all the "how to bootstrap a new project" guides just don't work.
• Elsa is at least at 2.8 now, and the docs are ostensibly for version 2.2
• The doc site lacks search. If there are any pages in the docs detailing how to enable features (such as WebHooks) I can't find them.
• Major features, such as how to enable Features, what features exist, are not even acknowledged as a thing by the docs.

My only comment regarding Docker is not enough use of Docker is made: A csproj ApiServer with docker based Dashboard is easy to setup but not mentioned. imo this should almost be the default quickstart.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[badihi]

A considerable portion of code lacks any kind of documentation. Not even a descriptive comment in the source code. For example I wanted to find out about the method AddCompetingMessageType(). I googled it and found nothing. I searched it in GitHub, but no XmlDoc or descriptive comments was available. Please see the situation from my perspective for a moment and tell me how I'm going to find out what AddCompetingMessageType() means at all?! The only way for a person like me is following the rabbit hole deep down into the source code to understand what it is doing. Each public method in the code must have at least a single line of description, and it is the least you can do about documenting your project.