Documenting the (Ancient) History of Your Project¶
Description
Hatshepsut, the second historically-confirmed female pharaoh of Ancient Egypt, was a great leader and innovator of her time, which we’ve all learned about through hieroglyphic-laden documentation. She’s also a victim of changes to documentation in an effort to erase her contribution to the kingdom’s feats. Luckily for historians, edits to stone are hard to conceal!
Often, the factors that are overlooked when writing project documentation are the historical conditions surrounding adoption and advocacy of a particular solution. Freshly hired software engineers at Relatively Sized Tech Company may have made choices based on the lack of information explaining tech stack history and the decision-making that frames it.
As an Egyptology-Major-turned-Engineering-Leader, I’m surprised by how little historical evidence is referenced when it comes to technical decisions, until I discovered the main cause: Documented context rarely exists. Oral tradition often reigns supreme. As technologists and writers, we should lead the change we want to see in robust, well-executed documentation.
In this talk, I’ll walk through some useful ways to ensure historical context is well-documented for your project, and why doing so at the project’s inception and throughout its maintenance is particularly important:
– Learning from archaeology to understand the human activity involved in technical projects
– When and how to document this activity, including decisions, discussions, and defeat
– Why timing matters and how changes after-the-fact can be harmful for future users and contributors
By applying an archaeological mindset to documentation, we can avoid the frustration that a lack of historical context affords, particularly when a team member leaves or a new pharaoh begins their reign. Let us all be diligent archaeologists and make the excavation of documentation a breeze for those who come after us.
- Conference: Write the Docs Prague
- Year: 2020
