Syndesis: discussion - where should the designs live

[gashcrumb]

Created from the start of this discussion -> https://github.com/syndesisio/syndesis/issues/1994#issuecomment-373449448

Let's get a conversation going to discuss the best place to store and manage designs so that the UI and UXD folks can most efficiently use their time.

Currently UXD creates PRs with .md files and screenshots exported from (invision? sketch?) and a lot of work goes into assembling each functional area. However we've hit a couple cases where the designs have fallen out of sync, or there's been confusion as to which design is accurate, single source of truth and all that.

I'm aware that we also want to ensure that epics should have all the information stored in them and I agree, but I wonder if the designs themselves should or should not be in git, i.e. is exporting the designs out of the tooling that UXD uses hurting us here? In an epic for example we could link off to relevant designs, rather than link to a .md file in the git repo.

Please discuss...

[amysueg]

Hey Stan @gashcrumb - @catrobson has encouraged us to use the "UX Work Tracker" like OSIO - https://fabric8-ui.github.io/fabric8-ux/designs/platform

@seanforyou23 & @michael-coker set this up for us in our old UX repo here, and I am planning to meet with @seanforyou23 next week so he can walk me through populating this with our designs: https://syndesisio.github.io/syndesis-ux/ @rhuss approved the use of the old repo for serving up this Git Page.

Moving to this type of 'dashboard' for designs removes some of the overhead for @dongniwang and @sjcox-rh to have to create pull requests and .md files for each of their designs. Rather, they just stay in InVision files that are then linked from this table view.

We ran it by @kcbabo some time ago and he liked the idea. Seems like a good time to move in that direction and help avoid 'out of sync' designs. UX team will discuss in our regular meeting tomorrow afternoon.

[deeleman]

Having a centralized source of truth is a must, definitely. A publicly accessible UX repository where all the Invision demos and final UIs screenshots (which should also contain a redlined version so devs can refer to a strict reference when setting paddings and margins) are located seems like a helpful resource that will prevent the major issue we have now: Every time the UI folks need to action on a specific feature, they need to (1) chase unicorns throughout a mesh of GitHub issues, most of them unlinked or even unrelated, to try (2) figure out which one of those designs was the most up to date one by comparing posting dates while (3) dealing with all the subsequent comments posted thereafter in the discussion thread just in case any of those comments proposed a different course of action, having to (4) gauge then the level of agreement on each of those comments to figure out (again) if that text change or suggested color replacement should (5) be taken into consideration or not. Should that naive UI developer dares to ask, we usually return back to (3). Loop and repeat.

Obviously I'm not exaggerating. Please take the following examples (I'll spare you the links) as a reference:

• Custom API Connector
• History Log
• Monitoring Metrics
• Activity Logs
• Etc...

Right after these multiple stages of iteration, the feature we've carefully crafted with love will make its way to QE. But, well, it turns out that the feature we're supposed to ship didn't have a spec with (UX/UI/E2E) acceptance criteria attached (because it simply does not exist), so the QE manager in charge will have to a) chase himself a pack of unicorns in the form of open/closed/archived ticket issues scattered across GitHub to learn how the hell is this feature supposed to work; or b) follow his gut. TBH, I recommend the latter, for the sake of his sanity. Given the enormous room for improvement that anything in this life has (starting from software design to my ridiculously miserable piano performance skills), no matter what option she picks, there will be a ticket springing at some point regarding a tweak on some text label, or a modal window that should say "Hi" instead of "Hi!" or whatever (usually this ticket will go through the same 1-5 process depicted above).

The process required for such tweak requires 3 times the time we need to actually apply it, because of the overall flow of tests/Git actions/PR reviews/CI mambo jambo... entailed on each new code iteration.

And then, my friends, we get to the moment we've been waiting for... That feature lands on some PM desk... And it turns out the text does not please him (regardless it might had been like that from the very first signed off design provided), and we see a brand new bug (bug? seriously?) report shining on top of the Issues list (let me spare you the links here too) saying that something is broken, or buggy, or flaky, or whatever name you want to put on it but which will break the poor UI dev's heart into a thousand pieces of sorrow and self-shame...

Let's hold a minute of silence for that poor (and depressed) UI dev... So we can hear the distant roar of GitHub's load-balancing servers getting ready for the dozens of thousands of issues that will get opened in the Syndesis repo in the forthcoming weeks just to model 4 or 5 new features...

Apparently, the UXD markdown files pull request-based process does not seem to work well, since it's hard to track down what UI is relevant and what is not in the moment that the PR is merged (not to mention that I guess it's too time-consuming for the UXD folks), so a better process is required here IMO. Having a centralized repository of Invision demos and (redlined) screenshots will become a very valuable resource to get a hi-level overview of the entire flow, but it will be overkill when it comes to action on a particular feature.

Up to now, features were documented as massive monolithic epics, attached to an endless row of design screenshots. Taking action on a feature like this is simply not possible, not to mention providing a time estimate for its delivery. Gauging its level of completion after that is simply ludicrous, which invalidates all the effort undertaken by product designers, engineers and QE teams thereafter.

For me (and for anyone who has been working on mature SCRUM teams), the ideal workflow should be:

1. The feature is discussed between POs, engineering leads and product designers
2. Product designers come up with a formal definition of UX, including user journeys and a close-to-final copywriting. All this before engineering get their hands on stuff: Guys... this is an UI PRODUCT, for Gods sake! No UX -> No product.
3. Engineering leads and UI developers work together to split the feature definition (which most likely now comprises a high level overview of the feature to ship and tons of screenshots and Invision interactive mocks) into small, actionable issues, formalized as GitHub issues labeled with a new label referring to the main feature (the infamous epic label). And when I say small, I mean: An issue should be actioned by no more than a API and UI developer and shipped in the very same day, or 2 days AS MUCH. If any given issue entails functionalities requiring more than 2 man work days, then it can be split up into smaller functionalities.
4. Each issue is then formalized on GitHub by populating its expected behavior, particular screenshot, link to Invision demo (if available), API endpoint paths, verbs and most importantly, typed schema (this is usually never provided and it's the source origin for 85% of the UI bugs reported). It is important to note that the attached screenshot should only refer to the particular functionality that is meant to be shipped at this stage of iteration, so the API/UI/QE engineers will perfectly understand what are they supposed to deliver and when, by having a clear and pristine definition of the scope. This does not require the UXD to create designs for each iteration stage: annotating, blurring or highlighting parts of the screenshots provided will just suffice.
5. Each feature is later on evaluated and assessed by QE following exactly the SAME expected behavior criteria described in the issue. If the feature fulfills the use case described in the _Expected Behavior_ section, then it will be marked as ok. Otherwise the SAME issue will be reopened (instead of filing up a new bug ticket, which goes against all modern QA practices).
6. If any QE/PM/Random contributor decides that whatever part of the product experience does not suit his personal views, he can always open an issue and properly tag it as Enhancement. We're an open community and every one should be free to contribute with improvements, but different views do not mean that this or that behaviors are bugs.
7. Go back to (1). Repeat.

We were kinda following this process till (3). From that moment on everything turns into chaos. This needs to come to an end, seriously.

My main point here is that having those designs in the GH issue itself and contextualized to match the issue _definition of done_ is really important. Building a particular feature but referring to a broader UX definition as a reference does not only add confusion to the UI stage but to all the subsequent steps in the process.

Turning the Gh issue description into the single source of truth is the way to go IMO.

[gashcrumb]

Turning the Gh issue description into the single source of truth is the way to go IMO.

+1 but I don't want that to mean all screenshots get put into the github issue description in the same fashion as the current .md files, I think we agree on that but want to call it out just to be on the safe side :-)

[deeleman]

but I don't want that to mean all screenshots get put into the github issue description in the same fashion as the current .md files

Exactly, each GH issue should only attach the particular screenshot which is relevant to that incremental piece of functionality, and probably the UXD folks will want to annotate said screenshot to point out what areas are not meant to become part of this iteration, should the original screenshot encompassed more content which is only meant for future development.

[gashcrumb]

I think now that we've discussed with UXD we have a plan going forward, i.e. we're going to use the design tracker, first thing that has to happen is the tracker needs to be populated with the existing designs. @amysueg is there an issue open tracking this effort or do we need to create one?

[amysueg]

i will create an issue for myself, and link it to this issue.
michael s is and i are meeting in exactly 41 minutes to populate the tracker.

[gashcrumb]

@amysueg awesome, thanks!

[gashcrumb]

Also we should probably consider either linking to the google document that was kinda describing the process from our developer handbook or maybe even migrate that content to the developer handbook for future generations to uncover. I can probably take that on in a few...

[gashcrumb]

Think this discussion is all set