1. 17

  2. 8

    Sounds similar in spirit to “Press release driven development” I’ve heard of being used at Amazon. If the imagined benefits to the user aren’t obvious or difficult to articulate then it’s possibly worth rethinking your approach instead of diving into development.

    1. 7

      I think I would struggle a lot with this. I’m a huge proponent of thinking before writing code, but I feel I get the most value out of writing the API first. Often times it takes a few attempts of playing with an API before really understanding what it should be. Writing documentation first would get in the way for that, for me.

      1. 7

        I think it highly depends on who your target is. For developers, well thought out APIs are great. But end users rarely, if ever, see APIs, they are a few levels higher, and at that point, I can easily see documentation taking over the role of APIs, from a design point of view.

        Next time I do something aimed at end-users, and not developers, I’ll give documentation-first a try, and see how it goes. It sounds like something worth aiming for.

      2. 3

        It’s a tough discipline, but well worth it if you can sit still long enough. My boss advocates this. He calls it the highest form of functional specification.

        1. 3

          I’m a big fan of this … I call it “Document Driven Design”. I think it is a lot like writing “user stories” and so on, but I find it a lot easier to stay focused on, acts as interim documentation for new members joining a project and as a bonus eventually can turn into the “real” README, manual, etc.