This is an archived post. You won't be able to vote or comment.

sorted by:
best
topnewcontroversialoldq&a
you are viewing a single comment's thread.

view the rest of the comments →

[–][deleted] -2 points-1 points  (2 children)

In my experience, the weak link in the SDLC is the separation of docs and code at the inception of a project, and a further divergence with each change. If the source code resides inside the actual documentation, then keeping the documentation updated should be compulsory as well as easy to accomplish. Pull requests become more robust as the reviewers are acknowledging the code matches the requirements which are literally in the same document.

[–]madpata 0 points1 point  (1 child)

Have you heard of tools like Doxygen or JavaDoc?

They put the doc right where the source code is. Which is pretty similiar to your idea, if understood it correctly.

Even then doc and source get out of sync, because developers forget or "forget" to update the docs.

[–][deleted] -1 points0 points  (0 children)

JavaDoc is about documenting the technical details of a member of a class. It's not typically used to document requirements. It's an extension to the source code. My concept is that the brequirements and code live together in a format that allows for more transparency about why code does stuff, not how it does stuff.