3 ms·

> So a well-designed interface or OpenAPI spec is worth its weight in gold. When I worked on a SOA team, I tried to begin any new effort (whether a new API or

> So a well-designed interface or OpenAPI spec is worth its weight in gold. When I worked on a SOA team, I tried to begin any new effort (whether a new API or modification to existing API) solely discussing the API contract. It was (ideally) high-level enough that business analysts and project managers would understand it, and it helped to guide us away from getting mired in implementation discussions too early. At that organization, we rarely had the opportunity to involve multiple customers at the same time during design discussions (we were typically engaged to help a specific consumer implement a specific feature), but the institutional memory in the SOA team helped us to keep in mind existing/potential other users of each particular webservice.

hinkley 7y ago
The last place I worked that split the devs into UI and backend teams was in a sort of slapstick comedy situation. Nothing ever shipped on time because the front end and backend could never quite talk to each other or needed elaborate conversations to do the simplest of things. This was our new flagship project, I got consolidated in from another team and ended up as a lead not long after. We had been doing some UML modeling, sequence diagrams during planning, and still having this problem, so rather than repeating the same action and expecting a different outcome I started trying to flip the script. What ended up working was not code diagrams but data flow diagrams and sequences. To get X you need Y, and to derive Z you need A, B, and X. To publish you need all five. After that, the APIs mostly wrote themselves, we reordered a few different forms, but most importantly variance dropped like a rock.
- username3 7y ago
  Can you share examples of your data flow diagrams? Do any open source projects share these documents?
  - hinkley 7y ago
    Mostly these were white boarded, but essentially I/we would draw a collaboration diagram (although I could have sworn these used to be called something else). They showed what data was needed to make certain decisions (eg, a conditional drop down that is populated based on another piece of data, or complex validation steps) and where to get data that already existed.
    - dionian 7y ago
      activity diagram?
      - hinkley 7y ago
        Yeah it looks like the activity diagram was substantially altered in UML 2.0. What we called an activity diagram then looks more like a collaboration diagram now.
  - Terr_ 7y ago
    Aside, take a look at tools like PlantUML as a way to create your diagrams. It's higher-level than, say, rolling everything with Graphviz, while easier to share and edit than a bunch of PowerPoint/Visio/etc. files. The great thing about generated-diagrams is that you can easily store and version the original text representation along with the code it describes or applies to. https://plantuml.com/ https://plantuml.com/

hinkley 7y ago

The last place I worked that split the devs into UI and backend teams was in a sort of slapstick comedy situation. Nothing ever shipped on time because the front end and backend could never quite talk to each other or needed elaborate conversations to do the simplest of things. This was our new flagship project, I got consolidated in from another team and ended up as a lead not long after. We had been doing some UML modeling, sequence diagrams during planning, and still having this problem, so rather than repeating the same action and expecting a different outcome I started trying to flip the script. What ended up working was not code diagrams but data flow diagrams and sequences. To get X you need Y, and to derive Z you need A, B, and X. To publish you need all five. After that, the APIs mostly wrote themselves, we reordered a few different forms, but most importantly variance dropped like a rock.

username3 7y ago
Can you share examples of your data flow diagrams? Do any open source projects share these documents?
- hinkley 7y ago
  Mostly these were white boarded, but essentially I/we would draw a collaboration diagram (although I could have sworn these used to be called something else). They showed what data was needed to make certain decisions (eg, a conditional drop down that is populated based on another piece of data, or complex validation steps) and where to get data that already existed.
  - dionian 7y ago
    activity diagram?
    - hinkley 7y ago
      Yeah it looks like the activity diagram was substantially altered in UML 2.0. What we called an activity diagram then looks more like a collaboration diagram now.
- Terr_ 7y ago
  Aside, take a look at tools like PlantUML as a way to create your diagrams. It's higher-level than, say, rolling everything with Graphviz, while easier to share and edit than a bunch of PowerPoint/Visio/etc. files. The great thing about generated-diagrams is that you can easily store and version the original text representation along with the code it describes or applies to. https://plantuml.com/ https://plantuml.com/