- Tags:: #📝CuratedNotes, [[Data methodology|Data Methodology]] ## Frameworks ### [The Grand Unified Theory of Documentation](https://documentation.divio.com/) Not all documents are the same: ![[Pasted image 20220708101447.png|400]] ![[Pasted image 20220831072818.png|400]] ### [How to Write Better with The Why, What, How Framework](https://eugeneyan.com/writing/writing-docs-why-what-how/) 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](https://medium.com/mercadona-tech/extreme-programming-for-writers-ff553e66848e) My own article about the place of writing in software engineering, specifically in [[Mercadona Tech|Mercadona Tech]]. ## My personal staple of documents - For Data Science initiatives, it all starts with the [[one-pager|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|Rfcs]]. - Exploratory [[Data analysis|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|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|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|Writing Tips]].