Re:How to Improve a Legacy Codebase
by cafard on Tuesday May 30, 2017 @09:58AM
(#14445382)
Frankly, I never quite understood the importance of clear documentation until I found one such code base smoldering on my porch.
[ Parent
| on HN ]
At the very least, write a doc that explains how to build the product, including where to find the parts in source control, what the dependencies are, what servers it'll get installed on, and so on.
The goal being to increase your shop's "Bus Factor"
> At the very least, write a doc that explains how to build the product, including where to find the parts in source control, what the dependencies are, what servers it'll get installed on, and so on.
... in the form of a Jenkins build configuration. (If possible; if the system requires legacy compilers that only run on old Windows versions or a proprietary compiler for an embedded target, good luck.)
The legacy projects are the ones where a doc with all that info would be the most useful. :)
Something to be cognizant of when creating this "keystone" doc - not losing it on some "share" that nobody can find anymore.
Thus, the use of README in the root directory of a project.
Since it would contain the location of the root directory, putting there would be circular. Hopefully the organization has a central location for their documentation that is somewhat organized (via SharePoint, or even a network share with folders). Reducing the number of things that a new hire would need to "just know" to a minimum should be a goal.
> Hopefully the organization has a central location for their documentation that is somewhat organized...
My office uses a combination of Redmine, Slack, email, gitlab, network drives, google docs, dropbox, some pdfs floating around, and a readme in the root of each repo...
Exactly. Because...
It started out on...
That Novell drive
... but then...
That Win95 share
... Samba
... Wiki
... Sharepoint
... nah, let's start using Confluence now
etc.
If you have it, it's nice to have a build/CI server that has a UI showing all the projects in a dept/work-group and where they come from in source control.