Camal (14) [Avatar] Offline
#1
Hi Kamil,
I just finished the first chapter of the MEAP version and I want to give you some feedback about it. No typos or image errors included, though the figure 1.2 has a order error smilie

First of all, thanks for writing a book about Specification by Example. I am a strong believer of this approach. I would love to see a sidenote in the first chapter that it is also known under other names as Behavior Driven Development and more. I used to get confused by a lot of names for the same things.

You mentionend in the beginning of the chapters change-tolerant processes and specification, could you also provide some examples in this fields?

It would be great if you could provide a throughout example of what a specification is, what a requirement is and so on. I got very confused by all the words and the different contexts you used in your text.

It would be great if you could explain it with a fictional example as "The team got a document with the the requirements xyz, xyz, xyz" This is a specification. Also I didnt get your explaination of the difference between a requirement and an acceptance criterion.

Your example "Does the system perform mobile payment" could also be answered as pass or failed.

"Without clear acceptance cirteria for each requirement, software dev. team wouldnt be able to plan any work ahead", I would say they could, but they would decide by they own when to finished. Maybe you can make your point a little bit clearer on this one.

The described conversations with the client are superb but it feels like that you often stop them sudden. For example the Edison Street disaster, you could add two more sentence, that the customer added Edison and got this result without any mention about streets or buildings.

At the part of 1.3.1 I would put more emphasizes on the ignorance of knowledge of the system to build. Building software that matters. Also you could mentioned that this strict approaches dont give for example "quite" people to speak up and maybe you miss good ideas.

At 1.4.1 you are mixing the flow by putting the explanation of capturing conversation at the end. This felt strange for me because the picture showed me a different flow.

To stay in the flow I would swap 1.5.2 with 1.5.3.

Also you mentioned it would be great to involve everyone. I would deny it. Everyone who matters. I think a workshop with just everyone would be a waste of time/money/energy. Just phrasing smilie

It would be super cool to add a fictional call at 1.6.1 to it. When people living to lunch put a phone call in it any then describe why this happened. This would add much value to it and it doesnt feel so a sudden text change as I mentioned before.

A cool thing would be definitely more example as for figure 1.6. Add some transaction from raw to refined to it.

The summary felt a little bit to long. Never saw a long list like that.

Thanks again Kamil for this book. I cant wait for the next chapter although I am pretty confused by all the words and contexts switchtes.

So here again my feedback:
  • More examples to clarify the keywords

  • Sudden Text stops or changes

  • More emphasizes on "Software that matters"


  • If you have any questions about my feedback, please dont hesitate to contact me.

    Chéers,
    Camal (Germany)
    Kamil Nicieja (1) [Avatar] Offline
    #2
    Hi Camal,

    Thank you for your feedback. It’s extremely motivating to see people interacting with the book despite its shortcomings at this early stage, and I think every MEAP author will agree with me. So, thank you!

    You mentionend in the beginning of the chapters change-tolerant processes and specification, could you also provide some examples in this fields?

    By change-tolerant processes I simply meant agile processes such as Scrum and Lean that optimize for iterative changes, small improvements, rapid prototyping, and investing in options instead of making commitments. I’ll clarify.

    I would love to see a sidenote in the first chapter that it is also known under other names as Behavior Driven Development and more. I used to get confused by a lot of names for the same things.

    That’s a great idea. I’m not yet sure, though, if such a sidenote should belong to Chapter 1 or Introduction.

    It would be great if you could provide a throughout example of what a specification is, what a requirement is and so on. I got very confused by all the words and the different contexts you used in your text.

    It would be great if you could explain it with a fictional example as "The team got a document with the the requirements xyz, xyz, xyz" This is a specification. Also I didnt get your explaination of the difference between a requirement and an acceptance criterion.

    This is something I will keep in mind. I think I might have shortened a few sections too much while editing. smilie

    At 1.4.1 you are mixing the flow by putting the explanation of capturing conversation at the end. This felt strange for me because the picture showed me a different flow.

    I understand. By talking about having conversations and automating conversations first, I’m trying to get buy-in from the readers. I’m trying to say something like "Here are the great benefits of building software this way" before I say "this is what you need to do to achieve these benefits" (capture conversations in Gherkin.) I think this approach is valuable, but I do agree that the figures suggest a different flow which is misleading. I’ll think of a better way.

    Once again, thank you for your feedback. It’s great and thoughtful. I’ll do my best to fix the things you highlighted. smilie
    —Kamil