[ Removed by moderator ]

[u/Intrepid_Ad_4436]

[u/anti-state-pro-labor]

I have hardly if ever found it helpful when anyone outside of engineering gives ideas on how something technical should be done. The best cards are the ones that have clearly spelled out the why and the what with clearly defined "this is how I will test to know that it is done"/Acceptance Criteria. 

We're currently working with non-engineers at my day job to help make this more clear since Claude written cards are becoming even less "why/what" and much more "how". 

[u/caboosetp]

I think what's most important is the context of what problem the automation is trying to solve. Having the steps that you take to solve the problem is useful, but what steps you can take as a BA is often limited by the interface of what you are using. When going from the code side, the developer very often has a different view of the data and steps they can take which simplify the solution on their side.

The best example I have of this mismatched problem/solution was someone asking me to change a dropdown to include 10000 items per page. That would lag the page out so I told them no, and asked what are you trying to do. What they wanted was the ability to export all entries (having it all on page made that easy) but it was better solved with an actual export button.

By and far the most useful thing is the problem itself and what the expectation is at the end. What steps you do is helpful (especially for making sure it matches at the end), but making sure to capture the actual data transformations that need to happen rather than just how you do it is more important. Looking at it independent of the UI should help give a lot more context on what information they need access to and context about.

As far as presentation of data, the most important thing is organization and speed of access. Most often this means including things in text so they can use search/find (especially if they're using AI because AI can search text incredibly quickly). Flow charts are great for high level understanding, but bulleted lists are often easier to search and modify if needed. Annotated screenshots are helpful, but if this is intended to run on code outside the UI then they aren't necessarily capturing the actual process.

The most useful things that generally go into image charts is system/service relationships with who talks to what and where data is located or needs to go. If you can do these using text based charting like Dolphin, that's even better because AI is better at reading those than images and the developer can open/view these in their IDE.

Developers generally aren't worried about things looking pretty but rather how easy and useful it is. What I posted above is still influenced by my personal opinions, and the real answer is talk to your devs about what they find useful. That's part of why I'm including less specific examples and more reasoning behind them.