Re:The case for continuous documentation
by daurnimator on Sunday June 06, 2021 @07:27AM
(#27412371)
None of this works if the programmer isn't the same person that writes the docs. e.g. if you have a copy-writer come along and write/update the docs before each release, then its not captured in the same commit/branch/etc.
[ Parent
| on HN ]
That can still work, in a couple of ways.
You can have the programmer write bad documentation and file an issue for it to be improved. You can then enforce that releases don't go out until those issues have been resolved by the copywriter.
You can also implement new features in a branch with multiple authors. The branch doesn't get merged until the documentation is in good shape.
It still works ok, just not as nicely.
The copy editor updates the repo and while their changes won’t be in the same commit, they should be nearby.
So you still get the benefit of docs history, and being in the same place.
Re:The case for continuous documentation
by skeeter2020 on Sunday June 06, 2021 @09:05AM
(#27412874)
I think you could also make a case that if you've adopted these strict documentation requirements you don't decouple the functional commits from the documentation commits. Your copy editor could work in the same branch as the code changes and then you only approve the PR when the documentation is at the same level of QA as the code. Otherwise a fear separate commits or branches is the thin edge of the wedge.
Sure it does, developers work with domain experts on features all the time. Perhaps you had SDETs adding some test infrastructure, or designers adding assets and layout information. Either you can have feature branches, or stubs/scaffolding for CI. I've seen both work.
The biggest issue I've see is management and product who seem allergic to the actual repos for some reason.