TL;DR: What would you look for in a collection of documentation when taking over an app to be run a larger scale than originally designed for?

I've been tasked with writing documentation for an application I've never worked on. It's legacy code that was written by an intern some years ago so it's not very well architected or documented within itself so "good code should explain itself" is out of the question.

What I need to do is compile some collection of documents that will help a team of experienced developers take this app and "manage" it on a much larger scale than originally designed for. I thought of breaking this down into four documents.

A user guide: Not being done by me.

A README: a document to go along with the source code that is your run-of-the-mill readme including things like instillation instructions and a high level overview of how things work.

A Help & Maintenance Guide: A document that hopes to cover the issues this team might run into while making updates to the app... I'm not sure where to begin this document other than a list of things I ran into when trying to set this app up/make some changes to it. Any advice on how to properly write this would be greatly appreciated.

A Systems Design Document: A more in-depth document that describes how the different systems interact with each other. What are the nice to have and required things to include in this type of document?

Is there anything I should include/not-included? How would you go about creating this type of collection?

Additional notes: I am myself an intern and have never successfully written really good documentation so I'm looking for advice from those who have.


1 Answer 1


I think that the pure-documentation strategy that you have outlined here is solid. (Presumably, other people will [also ...] be responsible for "taking a legacy application beyond what it was designed for.") I think that your plan reasonably "covers all of the bases."

Now, as you proceed with your work, first present your plan to the surrounding team (and, of course, your manager). Try to, so to speak, "sell it to them," then listen extremely carefully to their feedback and try to incorporate all of it. (After all, "they're your 'customers.'")

Likewise – and with constant approval of your management – regularly present your "works in progress" to the team. If you have issues and questions along the way ... as inevitably you will ... work with your manager to find an effective way to present them to the team ("customer") for effective resolution. In this way, you will help to ensure that your final work-product will be as beneficial as possible to those who will subsequently use it.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.