News for hackers. Stuff that matters.
Re:Four kinds of documentation by dtech on Friday October 18, 2019 @09:09AM (#21291044)
A separate specification works much better as long as that specification is also enforced during the build.

A separate openapi spec that is not enforced can quickly become outdated, then an auto-generated from code is better.

Re:Four kinds of documentation by undreren on Friday October 18, 2019 @09:29AM (#21291175)
You can add two new columns to your Kanban board called "Documentation" and "Documentation Review".

Then tasks cannot move to your "Done" column unless documentation is written and passes review. If you enforce column limits documentation it will also block other tasks if not completed.

Re:Four kinds of documentation by Waterluvian on Friday October 18, 2019 @10:31AM (#21291672)
In addition to this (and going a bit off topic). I've been adding checklists to Github PR templates (it's really easy[1]) for things like, "Did you re-read the relevant API docs? Do they need to be changed?" and it helps me a ton.

[1] https://help.github.com/en/articles/creating-a-pull-request-...

Re:Four kinds of documentation by undreren on Friday October 18, 2019 @10:47AM (#21291826)
Checklists work so well. A kanban board has all the same qualities if used correctly :)
Re:Four kinds of documentation by dtech on Friday October 18, 2019 @12:23PM (#21292688)
I have about as much confidence that is gonna work as I'd have in a (non-automated) "Test" and "Test review" column
Re:Four kinds of documentation by undreren on Friday October 18, 2019 @03:51PM (#21294538)
Cool.