0

Conditions:

  • stable legacy prod system
  • no Software Devs of the system are available anymore
  • app is maintained by Engineers, who do not have the same software dev experience like the original Devs and almost none for that specific system
  • there are issues requiring debugging of the code, and the remaining Engineers have to handle both the issues and the technical documentation maintenance
  • not enough documentation usable for debugging and maintenance purposes of is available
  • code repository is the only reliable source of technical documentation for this case
  • only limited effort to improve documentation for this system is allowed (something like 80/20 rule)
  • format of the solution needs to be as universal as possible so that it can also be applied to other projects with similar conditions, and possible to be used as a baseline and guideline, that only needs smaller adjustments specific to each case
  • when solution is applied to a non-legacy system, it should still be sufficient, once it becomes legacy
  • the amount of prep work before actually create or update the project documentation should be either minimal or none (so no setting up external documentation systems and the such)

Question:

What specific tools, practices, or methodologies that have been successfully implemented in similar legacy environments can be used to create and update technical documentation to be minimal yet effective, when limited by all of the above conditions?

So far the below is the best method I managed to come up with:

  • Just start with the 1st source code file you have to touch and gradually go through each source code file to try to understand what it does
  • apply the Scout Rule ("leave everything cleaner than you found it") like described in https://softwareengineering.stackexchange.com/a/137953/440463 AND put a header on top of each source code file like described in https://stackoverflow.com/a/49438334/3853744 (basically add a "table" with various metadata about the source code file written as a text on top of the file, containing among others creation date, description, affected, usage and parameters, summary of changes with time, author and comments)
  • Put a README file in the top level directory of the code repo, which will inform how to navigate to find the technical documentation in that repo
  • Put another txt file in each "major" directory of the code repo, where any other technical info is placed, if it does not belong to just one source code file header
  • Since it is undesired to have long comments surrounding actual source code, use some sort of "KB1234" or "0x12345" numbers for the role of tags or labels in the text files and source code for each major component. It will allow to quickly find things that are related, for example with grep. These have to have a format that is unique enough that it does not generate too much incorrect finds

Background context, can be ignored if doesn't help with the answer.

You should not rely on links from source code to Jira or Confluence. After these have been migrated in our case from on-prem to cloud all links that were in source code have become broken. This made it extremely time consuming to find anything useful by hand because of reasons like for example the following: DependenciesCheck.sql should be called DoItAll.sql instead.

Since it is legacy, bringing the documentation in line with current trends and best practices is unfortunately not an option here as only limited effort will be allowed to be put into it, making the unfortunate reality that the source code repository is the only reliable place with any technical documentation for it, and potentially smallest effort as well.

My experience tells me that solution to this problem will continue to be applicable to most source code cases for a long time.

Update: Reformatted the text to improve clarity

stack3r
  • 125
  • 4
  • ... BTW, I think your current approach of improving the documentation looks good. Who told you this is not a good practice? For me, "best practice" is to stay pragmatic and adapt any invested effort to the specific resources and needs of a project environment - it sounds you are already doing this. – Doc Brown Feb 07 '24 at 14:54
  • @DocBrown I have updated the question text in yet another attempt to make it clear and focused. – stack3r Feb 07 '24 at 15:21
  • One thing which bothers me is the content of the header. A high level description is good. Input and output descriptions are good. Nonobvious usage information or side effects are good. What I would avoid is to put anything into which can be easily retrived by anyone from source control, like creation date, original author or summary of changes. – Doc Brown Feb 07 '24 at 16:26
  • @DocBrown - I get where your point comes from, and probably in most cases this is sufficient. However, not so long ago, I had to merge and migrate multiple SVN repos into one Git repo. Due to limitations of such process, sacrifices had to be made. Some of the metadata, including creation time and most of commit info got lost in the process. In that case at least the major "milestones" could be preserved in such header, as I would not want a commit history duplicate. BTW, what is missing for reopening my question? – stack3r Feb 07 '24 at 22:53
  • There is a 3rd member missing with enough rep willing to cast a reopen vote. I casted my vote for reopening already yesterday. But to what you wrote: I would not duplicate the change history into the source code files just because there is a minimal risk in some years they history could be lost due to a change of version control (something for which the chances are quite low when you nowadays work with Git). I would instead invest a little bit more time into the migration process to migrate the meta data when it ever comes to that situation. – Doc Brown Feb 07 '24 at 23:15
  • @DocBrown - thanks for the vote. I generally agree with your approach, which is why I mentioned milestones as probably the only relevant historical changes, but I am actually still investigating what makes most sense and/or if there should be just one "template" for this topic. Maybe there are already good examples for both directions. Lets see what answers come up. – stack3r Feb 08 '24 at 08:26
  • Let us continue this discussion in chat. – stack3r Feb 08 '24 at 08:28

1 Answers1

3

Considering the limitations described above, how can I create or improve documentation within the codebase to ensure it's comprehensive and accessible for technical staff who aren't developers? I'm looking for strategies or practices that help maintain documentation's relevance and usefulness, for the purpose of maintaining the app running, resistant to issues like above migration.

You can adopt (and try to get the rest of the organization along) the philosophy of Docs-as-Code. The heart of this philosophy is that the documentation lives alongside the code in the same repository and gets the same treatment.

With Docs-as-Code, the documentation is typically written in a plain-text markup format (like Markdown, AsciiDoc, reStructuredText, etc.) and the build street generates a version from it that can be published (for example as PDF or HTML) for people who don't read markup natively.

Docs-as-Code does not assume that the documentation is in the same files as the source code. We also use it for really high-level architecture documents, written in AsciiDoc format, that describe which services exist in our environment.

Bart van Ingen Schenau
  • 74,630
  • Yep, we started this for a certain product with a docbook toolchain ~20 years ago, and it still works well. Today, if we had to start over, we would probably try AsciiDoc. The only drawback is, it is hard to get non-developers on-board with that toolchain for writing end user documentation. – Doc Brown Feb 06 '24 at 22:39