How to document a new codebase
Use this template to document a new codebase.A place to record any important logic that you come across that is worth documenting.
Refers to the different landmarks of a codebase to help you navigate around. Where are the API methods defined? Where are interactions with the database?
Link to any documentation you come across that may help you better understand the codebase. Include documentation on the specific codebase, videos you find (check rewatch!), as well as documentation on the technologies used that you come across, in case it helps you refer back to it in the future. Make some notes or check things off as you go through them to keep track of which you have already reviewed.
Instructions on how to get a local environment up and running as well as any tips for testing specific things (ex. testing a specific type of customer which may have a different experience from others).
This is a place to track updates to docs as you come across them while learning a new codebase. Track things like where information is missing, where information is duplicated, anything that you think can be updated to be more clear, etc. It may be a good idea to wait until you have a picture of the entire landscape of documentation prior to recommending changes.
Throw any questions that you think of here. If there is an area that you don't know about and want to explore, add a question to explore it in the future.
Create diagrams of the overall flow as well as entity relationship diagrams of the data as you work through the system. Included are some mermaid diagrams to get started.
- Repo Link
- Technologies used
- Acronyms and Terminology
- Issues, PRs, etc., of recent changes to the codebase and what they were for
- How to get a development environment setup
- Important scripts to know
- Tips to test different scenarios
flowchart LR
id1[(Database)] --> API
erDiagram
CUSTOMER ||--o{ ORDER : places
CUSTOMER { string name string custNumber string sector }
ORDER ||--|{ LINE-ITEM : contains
ORDER { int orderNumber string deliveryAddress }
LINE-ITEM { string productCode int quantity float pricePerUnit }
I want to ask how you generated those SVG diagrams or what SW do you use for that? thx