Muhammed Senussi
Muhammed Senussi
  • Muhammed Senussi
Documenting a System Nobody Wrote DownSoftware Architecture

Every consultancy engagement starts the same way: the documentation is three years old and describes a system that no longer exists.

Read the artefacts that cannot lie

  • The deployment pipeline lists every deployable unit. That is your true component inventory.
  • The alert definitions say what the operators are actually afraid of.
  • The database migration history is a timeline of how the domain model really evolved.
  • Commit frequency per directory tells you where the system is alive and where it is fossilised.

Interview people after you have read those, not before. You will ask better questions, and you will be able to tell the difference between how the system works and how everyone believes it works — which is often the most valuable finding of the engagement.

2 Comments

  • Omar Haddad

    November 12, 2025

    قائمة التنبيهات كمصدر توثيق فكرة لم تخطر لي. ما الذي وجدته فيها عادةً؟

    • Muhammed Senussi

      Muhammed Senussi

      AuthorNovember 12, 2025

      أكثر ما أجده هو تنبيهات على أنظمة قيل لي إنها أُوقفت، وتنبيهات مكتومة منذ سنتين لأن أحداً لم يعد يعرف ماذا تعني. الاثنان يخبرانك بالكثير عن حال الفريق لا عن النظام وحده.

Leave a comment