- Tags:: 📝CuratedNotes, Data methodology
Frameworks
The Grand Unified Theory of Documentation
Not all documents are the same:
How to Write Better with The Why, What, How Framework
Most documents need this:
Why: Start by explaining Why the document is important. This is often framed around the problem or opportunity we want to address, and the expected benefits. We might also answer the question of Why now? What: After the audience is convinced we should solve the problem, share what a good solution looks like. What are the expected outcomes and ways to measure them? How: Finally, explain How you’ll achieve the Why and What. This includes methodology, high-level design, tech decisions, etc. It’s also useful to add how you’re not implementing it (i.e., out of scope).
Extreme Programming for Writers
My own article about the place of writing in software engineering, specifically in Mercadona Tech.
My personal staple of documents
- For Data Science initiatives, it all starts with the One-pager. I never had the need to use it for software eng. initiatives because they seem easier to be aligned.
- In a software team, any big feature and/or feature with no evident implementation should have its own RFCs.
- Exploratory Data Analysis docs: hard to make a template of this, depends on the exploration. I wrote some guidelines in Typical Workflow and Definition of Done for data analysis. Should be centered around questions. It should still contain the Why, What, and How.
- Experiments evaluation docs: should at least contain what is being tested, assumptions and a conclusion. We could have a document per experiment or one gathering several experiments. These could be the docs that are shown as part of the Demos.
- Runbooks or how-tos. People should go more straight to the point on these docs. The Grand Unified Theory of Documentation above explains them really well.
- Postmortem documents
- Sprint summaries: a high level summary of what we achieved in a particular sprint. It is useful not only to communicate with stakeholders, but also for oneself, as it forces you to think at a higher level than “task” level.
- Literature reviews.
Resources for technical writing
See Writing tips.