Auto-Documentation Tool IS HERE!

Feedback Studio
, ,
4

First of all, congrats on building this :tada: I really mean it.
And putting the code out there? Double awesome!

Will I use it? It makes me sad, but no, not in its current state.
Don’t let that discourage you, though.
Here are some things that make it a no for me (and take all of the things here as just my opinion/reflection):

  1. I couldn’t find it in Marketplace, even though you list that it’s there (that could be just me, or the search algorithm being wonky).
  2. Your GitHub repo does not state under what license this is available → that’s an immediate “can’t use it” in any business context, not even to try it out.
  3. This is effectively a Studio plugin from an unknown source - that’s a high risk scenario. I don’t only mean that “oh, there could be backdoors” and so on, but also from the angle of “if this is actually good, will it keep being supported?”.
  4. Your highlight video does not show the most interesting thing → the outline. The rest is much less interesting (to me).
  5. In the repo I saw that it has specific handling for If and TryCatch, but not much more (or I missed it). Could it handle Flowcharts? State Machines? Switches? Loops? RetryScopes? All of those are very interesting to see if they’re used.
  6. Does it support coded workflows? I don’t know. It looks like it might, but there’s nothing indicating that it does.
  7. The output documentation on workflow level is not that useful (potentially outline aside), or I’m missing something. Namespaces and References I don’t care about too much, neither are the Variables - all of that is an internal implementation detail that when reading the docs is not important (to me). I understand that these could be removed from template. WorkflowsUsed, UsedByWorkflows, and Tests are good. Arguments are ok.
  8. Expanding on previous point - why are these things not interesting? Because they’re in a separate file for each workflow. So if I’m a developer, I need to click through all of them individually, likely in source control. Which leads us to - why? Namespaces, References and Arguments are on the top of my .xaml file, so it doesn’t bring any additional value. So are Arguments at the top. I can see the workflow name before I even click it. So if I’m clicking through the files one by one, I might just as well click through the actual xaml’s. And if I’m not a developer, then none of the info here is interesting to me, maybe aside of the Name and Description. That’s the first and foremost biggest thing with auto generated documentation - if it just repeats what’s in the code, and the target audience is the developer, then why am I not looking at the code instead?
  9. Docs on Project level face a similar issue - it repeats what’s in the project.json. I know that it can’t do much more, but still - why should I look into it instead of the (already much more readable than xaml’s) project.json?
  10. If you’re doing an open github repo, please work on your commit messages. While they’re fun to read as a fellow dev, they don’t inspire confidence as a potential user.
  11. We already have an in-house auto-docs solution that does what this tool does and quite a bit more, although I’d happily discontinue supporting that the moment there’s something better available (it gets annoying to keep adding new things or keeping support for all project versions from 2018 to now :wink: ).

Again, these are only my opinions. You’ve built it, you find it useful, you shared it, and you made the code available. That is great and should be commended! Please treat above as just some unsolicited feedback from a fellow auto-doc creator :slight_smile:

PS: Feel free to drop a PM if you’d like some feature inspirations :wink: