Life used to be simple.
Client wrote down what they wanted, programmers translated it to code, testers validated that against what clients had written down.
Now we have tickets, where BA's (but most of the time developers, really) write down the lore that is told in numerous meetings.
Tickets are supposed to be ephemeral but never really are, that's why we keep some of the lore in Wikis. Except Wikis are good for text, not so good for everything else, that's why the lore spreads to Figma, Excalidraw and Google Sheets (if you are lucky, xls documents on Sharepoint if you are not).
Now we start coding. Some of the lore get's solidified into code, which is good, some turns into
tests which is good too, if you are lucky some turns into formal spec a tool can check.
But, there is always something left that gets spread evenly - more or less - across regular comment, doc comments, commit messages and various md files, most notoriously the README.md.
Which brings me to user documentation which again is often spread over the whole oeuvre of documents and systems we mentioned. Not to mention the confusion of most documentation about its intended target group. Is it user documentation for the enduser, really? Rarely!
Oh, and then the CHANGELOG that really wants to be release notes, but isn't, at least not entirely. Which is generated automatically, but isn't, at least not entirely.
Finally comes QA (but most of the time developers, really) but it doesn't have anything to validate against, so all they do is compare the faint memory of the lore they had heard in numerous meetings against what they have written down themselves in numerous places and are mostly content with the results most of the time.
Client wrote down what they wanted, programmers translated it to code, testers validated that against what clients had written down.
Now we have tickets, where BA's (but most of the time developers, really) write down the lore that is told in numerous meetings.
Tickets are supposed to be ephemeral but never really are, that's why we keep some of the lore in Wikis. Except Wikis are good for text, not so good for everything else, that's why the lore spreads to Figma, Excalidraw and Google Sheets (if you are lucky, xls documents on Sharepoint if you are not).
Now we start coding. Some of the lore get's solidified into code, which is good, some turns into tests which is good too, if you are lucky some turns into formal spec a tool can check.
But, there is always something left that gets spread evenly - more or less - across regular comment, doc comments, commit messages and various md files, most notoriously the README.md.
Which brings me to user documentation which again is often spread over the whole oeuvre of documents and systems we mentioned. Not to mention the confusion of most documentation about its intended target group. Is it user documentation for the enduser, really? Rarely!
Oh, and then the CHANGELOG that really wants to be release notes, but isn't, at least not entirely. Which is generated automatically, but isn't, at least not entirely.
Finally comes QA (but most of the time developers, really) but it doesn't have anything to validate against, so all they do is compare the faint memory of the lore they had heard in numerous meetings against what they have written down themselves in numerous places and are mostly content with the results most of the time.