1 comments

  • gojkoa 14 minutes ago

    the problem with user guides in general as a driver of specs (this is coming from surviving two such attempts 20 years ago) is that user guides tend to be written for an external audience, hiding a lot of complexity and underlying details. Sometimes this is to keep user docs focused on a specific task, sometimes this is because you don't want to disclose internal workings of a system to users).

    Specs can influence (and potentially be even a source for generating parts of) user docs, but user docs can't replace specs.

    On the other hand, the idea to write the guide, do mockups etc first is a great way to think through what the user would experience before you do the specs. We have something similar with agents creating demo pages so we can check them, and they become parts of the spec (and something to match the final product against).

    But that's not a good fit for backend processes, cross-functional concerns (performance/security) etc, or things you do because your business needs it and not the users (payment fraud prevention) that also need to be specified