To learn how to use Elsa, a developer should be able to read API & usage documentation

[craigfowler]

One of two "elephant in the room" issues relating to docs. This one deals with docs that developers will want to read, wheras elsa-workflows/elsa-core#701 deals with docs for users. Developers will need some documentation for Elsa 2.0. We are going to need to decide how much we are planning on preparing, and start scheduling the work to write it.

It might be best to treat this particular issue as a spike, with the intended outcome of analysis & agreement. That way this issue doesn't inflate like a balloon and become a never-ending "Do all the work!" issue. In that case, the outcome of this will be to create a series of follow-up issues to write specific, agreed-upon pieces of documentation.

Here are some ideas of docs which developers might want to read. We could use this as a starting-point for discussion, and it's almost certainly not complete:

• Installation & set-up
  • How to use each of the persistence back-ends
  • How to install & integrate with some of the other elective techs (Hangfire, Quartz etc)
  • This probably doesn't need full docs, because we can refer to docs for those techs
  • Setting up the dashboard/designer
• Conceptual overviews
• Integration with other technologies
  • ASP.NET Core
  • Dependency Injection
  • Logging
  • Again, not all of these need full docs, because we just need to point out that we use XYZ known mechanism
• Extending Elsa: Creating your own activity classes
• Minimum requirements
  • Compatible runtimes
  • Browser compatibility for the dashboard/designer
  • Compatible persistence back-ends
• API docs
  • Specific service interfaces which devs should know about to perform common tasks
  • Like some of the stores, to get workflow instances and definitions
  • Triggers & signals
• What's available?
  • A list of the elective NuGet packages
  • An overview of what each one provides

Acceptance criteria

Presuming we treat this issue as a spike, then the team should have worked-up and agreed upon a list of developer documentation topics which we plan to provide for Elsa 2.0. In that case, further issues should be created and scheduled so that each of those may be worked-upon.

[VahidNaderi]

Craig should we move documentation stuff to elsa-website?

[craigfowler]

@VahidNaderi right now, sure, I'm cool with that. I'm thinking of (after v2) suggesting that docs & the library itself are maintained from the same repo & github project, but I'll wait to "formally" make that suggestion.