Email or username:

Password:

Forgot your password?
Top-level
Donald Ball

@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.

4 comments
Jim Flanagan

@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.

Donald Ball

@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.

Donald Ball

@jimfl @mhoye The important things are really to involve the technical writers as first-class collaborators and, whenever practical, use data structures instead of raw code constructs at the documented contract layer.

Jim Flanagan

@donaldball @mhoye

> @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)

Go Up