3

I have coached my team to write quite good user stories using gherkin, but their technical stories are still lacking something.

The problem is that when a person of one technical discipline reads the story of a another technical discipline we are finding it very hard to convey enough meaning such that every technical team member can understand it (regardless of whether they know enough to estimate.)

An example, though not specific to our case, would be that of a C# developer without SQL skills writing a story in a team which includes SQL developers without C# skills. (I recognise that the former is unlikely but the extant teams of the latter are common, so please bear with me.)

We would like the story written by the C# developer to be in a grammar understood by the SQL developer. When the SQL developer writes stories we would like the same grammar to be used. I guess that this would be the technical lingua franca.

The user story's lingua franca would be gherkin. What could be the technical story's lingua franca?

|improve this question
  • 1
    Can you please share an example of technical story? – Aziz Shaikh Feb 6 '19 at 11:20
  • 2
    I specifically avoided providing an example of a technical story because doing that would cause focus on a particular technical language and that's not what I'm asking for. For example, if I provide a story for a change to a stored procedure, the discussion would inevitably become about how to write a good SQL change story. What I'm asking for is how to write a technical story which - while it may contain technical, language specifics - describes a change at a non-user or non-interface level in a technically broad way. ie: a technical change which all the tech people can grasp. – Matt W Feb 6 '19 at 11:28
  • 3
    What is the difference between a user story and a technical story? – Bart van Ingen Schenau Feb 7 '19 at 12:19
  • TBH, you should be asking that in a post, but in short they represent who the client for the work is. One is a human user, one is a machine user. Even shorter: Human or service. One needs a user interface another needs an API. – Matt W Feb 11 '19 at 8:14
  • 1
    Normally, technical stories only exist as a shortcut between two parties speaking the same "language". If your technical stories are no shortcut for you, why do they exist? Why not have normal user stories? – nvoigt Mar 12 '19 at 16:49
2

Gherkin is probably going to be the best fit for your situation, largely because you're using it today. If your team(s) are following a BDD approach, even more so.

For the example of a change to a RESTful API, I would write something like the following:

Scenario: Registered web client calls Foo(int id) method to get a list of Bars.
GIVEN: The client is a registered user of the API
WHEN: The client calls the Foo(int id) method
THEN: The API will retrieve the list of Bars for the passed ID
AND: The API will return the list to the client

Or...

Scenario: Registered web client calls Foo(int id) method with an invalid ID.
GIVEN: The client is a registered user of the API
WHEN: The client calls the Foo(int id) method
THEN: The API will fail to retrieve the list of Bars for the invalid ID
AND: The API will return the following error message to the client: "Bad ID!"

These are trivially short examples, yes, but kind of give a framework to use.

If I'm missing the mark with respect to the actual problems you're running into, provide another example, and I'll edit the post.

|improve this answer
  • 1
    I like this because, as with user stories, the scenario defines the changes required at the interface level and this works nicely with RESTful APIs, which are also a commonly understood technology. In my specific case (though I didn't really want to go here) the challenge is C# and SAP - not much cross-pollination and as such writing stories, even at the interface level, is challenging. – Matt W Mar 12 '19 at 14:30
  • 1
    That's definitely understandable. One alternative solution might be to see how they've been handling API requirements across teams in the pre-Agile days and then to slowly migrate them in a better direction. Even those old interface specs (or whatever) might end up being the right way to do it now. – DPH Mar 12 '19 at 18:07

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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