Gregory's Server@mhoye Even if the docs and error messages were lovely, they would so rapidly diverge from the fact of the code as to be wrong as a running clock (not even right twice a day, like a stopped clock).
|
5 comments
 @donaldball @mhoye I once had a conversation with a colleague about whether we could enforce this with an automated mechanism. Commits or PRs where code was changed but lacking changes to associated comments would fail. It came down to being able to detect, in any given programming language, which comments were about what code, which seemed like a hard problem.  @jimfl @mhoye I have had good success when given the appropriate resources by various combinations of having technical writers flagged via codeowners for e.g. the api contract declarations, having technical writers skim review all changes on a formal release, and providing a clear and actionable grammar style guide so software engineers have a fighting chance to get it right when they write their own. > @jimfl @mhoye whenever practical, use data structures instead of raw code constructs at the documented contract layer Nouns (data structures), verbs (API actions and events), and admonitions (what can go wrong) |
@jimfl @mhoye This doesn’t have to be true. If the (reference) documentation strings are part of the source code, and are actively maintained therein by both software engineers and technical writers in collaboration whenever changes are made — and more generally, if providing good, accurate documentation and errors is a considered and intentional aspect of your software architecture — this is eminently possible.