2

Currently, I'm designing the intended operation of a (RESTful) API which a team of developers will eventually build. I'm not concerned with implementation details, as long as inputs are correctly mapped to outputs (and data in the database won't be messed up :-)). To me it's not important whether it's built in an OOP or FP manner for example.

The problem: communicating the intended inner workings / business logic of the API in such a way that business people can understand what's going on (and hopefully provide feedback), and that developers will be able to write stuff that does what it's supposed to. So, it needs to be fairly abstract but still needs to contain enough detail for the developers.

The specs are primarily intended to be consumed by the devs. Business people should be able to understand them, but it's crucial that they contain enough information for the devs to start building.

By all means, I guess it makes sense to describe each user interaction (or API endpoint) separately. They could be described in roughly the following format:

  • Description (e.g. 'creating a user account')
  • Input parameters (data to be provided by the user, e.g. 'name', 'e-mail' and 'password')
  • Process (some sort of representation of the inner workings and outcome(s))

Makes sense? Am I missing important stuff here?

What would be the most suitable format to represent the process?

Pseudocode won't make too much sense to the business people. Automated tests will be written (and used by the devs) but the business folks won't read them.

Currently, I'm leaning towards flowcharts. They're visual in nature, easy enough to understand when done well and able to contain the required amount of detail (such as conditionals). It's possible to refer to the entities and attributes of the ERD that will be stored in Confluence (our documentation system) as well. Annotations can be used to provide additional (technical) detail.

Is this a reasonable approach? Are flowcharts a decent solution in this situation? Any better options?

Improve this question
2
  • 3
    Again, trigger-happy downvoters around here. An on-topic question, clearly written, gets a downvote without a comment, not even a close vote which could indicate a possible reason for the downvote. Come on, guys, you can do better, that's exactly the kind of behaviour giving newcomers an unfriendly impression.
    – Doc Brown
    Jun 21, 2018 at 21:11
  • 3
    I don't think you should be communicating the inner workings of your programs to a business stakeholder. Understanding the inner workings of the software you write is your job, not theirs. Their job is to communicate their requirements in sufficient detail and clarity so that you can work out the business logic that you need to satisfy those requirements.
    – Robert Harvey
    Jun 21, 2018 at 21:51

2 Answers 2

Reset to default
2

The correct or "best" means to describe functionality of an API depends on the specific functionality, there is no simple, braindead "one size fits all" solution for this.

For some functionality, flowcharts may be a good option. For some, data flow diagrams may be better. Organizing process descriptions in terms of "input, processing, output" is a very old, but still very effective technique. For some aspects, a representative choice of examples will serve best - the latter could be also wrapped into "user stories". And tables with attributes (and maybe datatypes) will also be understood by developers and trained users as well. Some users may even understand ER models (but be careful, normalization can be already too technical for several users).

"Domain Driven Design" tries to approach the problem by creating an ubiquitous language, a language with less ambiguities and clear semantics for users and developers - that is also a good idea for certain domains, if you are doing DDD or not.

But in the end, you need some years of experience to describe functionality in a precise manner, finding the right level of abstraction for your audience, using natural language which is not too scetchy and not too formal. This is something you cannot just learn from books or from an answer here on this site, you need to practice.

Almost forgot this - Joel Spolsky wrote a nice blog post 18 years ago about how to write functional specifications. That is probably a good example for what you asked for. To cite his introduction:

A functional specification describes how a product will work entirely from the user’s perspective. It doesn’t care how the thing is implemented. It talks about features. It specifies screens, menus, dialogs, and so on.

so avoid to focus on the "inner workings" (as @RobertHarvey wrote in his comment, too). Focus on what a function does, not how.

Improve this answer
1

I think you are still thinking like a developer or architect, and you need to think more like a user / product manager / business analyst.

Can you describe the workings of the API in terms of user stories or use cases? These are less technical but have a high impact if done correctly.

Improve this answer
2
  • I should clarify that the specs are primarily intended to be consumed by the devs. Business people should be able to understand them, but it's crucial that they contain enough information for the devs to start building. The inners workings can indeed be described in terms of user stories and use cases. To some extent, that has been done already during the interaction design phase.
    – Willem-Aart
    Jun 21, 2018 at 19:41
  • To build on the example given in the original question: it should be described that, during user account creation, password requirements are to be enforced. The exact password requirements must be described as well. Also, it should be clear what will be returned to the user when the provided password (does not) meet the requirements. A lot of details but given our situation it's essential to write that stuff down.
    – Willem-Aart
    Jun 21, 2018 at 19:50

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.