Thanks for the thoughtful response, this is helpful.
> Ideally it should be in version control and be generated from the code ..
May I ask if you have suggestions for tooling to capture the high level documentation. We use javadoc a little, but it seems best for lower level reference. Also for diagrams, like sequence diagram and/or state machines, how do you capture this?
Use graphviz (dot tool for example) for state machines.
It is a text format where you list state machine transitions and it generates a visual representation.
Or better yet: generate your state machines from same format you would use to generate visual representation.
Don't be afraid of building a product specification, and doing it in Markdown and auto-generating a mini-website out of it.
Just build a product specification for how the product works (which is useful documentation), not how the product will work (which is waterfall).
We're experimenting with this a little, and I'm getting into document-driven development a little: if the product spec is in markdown, why not create a pull request on it as part of your story/project planning that shows the changes that would happen as a consequence of your work. Once the story is done, you can merge the pull request, even. We're not quite there with this yet, but I'm optimistic.
> Ideally it should be in version control and be generated from the code ..
May I ask if you have suggestions for tooling to capture the high level documentation. We use javadoc a little, but it seems best for lower level reference. Also for diagrams, like sequence diagram and/or state machines, how do you capture this?
Thanks.