e Azure runner Principess a Punk nel💖 Madre dei draghi delle figlie Microsoft MVP BizApps & M365 DEV Amo parlare di M365princess. com DevOps • UI • documentazione accessibilità 42 OPEN so(u)rceress Cambiare il mondo un'app alla volta Luise Freese she/her 👠 #SharingIsCaring molto felice #ff69b4 It depends! molto nerd 🤓 Trouble Maker ✨ (Voglio tutti i carboidrati!) 👑 🧘 🏳🌈
e Azure runner Principess a Punk nel💖 Madre dei draghi delle figlie Microsoft MVP BizApps & M365 DEV Amo parlare di M365princess. com DevOps • UI • documentazione accessibilità 42 OPEN so(u)rceress Cambiare il mondo un'app alla volta Luise Freese she/her 👠 #SharingIsCaring molto felice #ff69b4 It depends! molto nerd 🤓 Trouble Maker ✨ (Voglio tutti i carboidrati!) 👑 🧘 🏳🌈
hates writing docs and will die on the hill of self- documenting software • A developer is a person who heavily relies on written docs and will complain to everyone if they’re not extensive enough
of a project telling you which npm package to install plus a GitHub sponsor link? • A printed manual on how users shall use the software in question, sold for 24.99$ (will get dusty on the shelf)? • Inline-comments everywhere to explain every single line of code (super annoying) • Something we honestly plan on doing if – by any chance – all stars align and we still have time/money/nerves left at the end of a project (never happens)
Design Description (SDD) The ugly truth Source Code Documeantatio n What people think is docs UX Design Documentation Mostly abandoned API Documentation Responsible for 80% of dev pain Test Documentation 🤐 Product Roadmaps Big picture
•Describes a software system to be built •Lays out functional and non-functional requirements •Includes a set of use cases 💡Basis for an agreement between customers and contractors/suppliers on how the software should function
this document •Contains the software design and overall architecture •Keeps the whole project team on the same page •Helps to ensure that all stakeholders vet the entire design and that all risks and assumptions are considered
by itself is not self-evident •Release Notes (best approach is to automate the use of commit messages) •Needs to be up to date – no one benefits from anything written months ago
the product design • It begins at the requirements stage and proceeds through all the stages of development, including testing and post-release stages • UX documentation covers • user personas • user scenarios • user story maps • a UX style guide, which includes an accessibility guide as well
and time constraints • Not well-defined requirements and not identified risks increase likelihood of redesign later on: cost overruns • Well defined requirements and risk awareness increase probability that project satisfies budget, quality and time
scattered is hard to find and easy to lose • A central repository of all product-related information helps developers and other stakeholders find the required information quickly
during software development projects can help teams improve their work on future projects • In this way, time and cost will be saved, and product quality will improve
during the debugging process and maintaining the software • It provides necessary insight into the thought processes of the original developers and can greatly expedite the process of finding and fixing issues
effort upfront • it saves more time and effort in the long run • It reduces the need for developers to figure out what the software does or how to use it every time they work on it
iterations of the software • By knowing the current state of the application in detail, developers can more effectively plan for new features or changes
regulated industries like healthcare or finance, documentation is not just useful but a legal requirement • It can be used to prove that best practices were followed or that certain functionality exists
Criteria • Clear Descriptions - what needs to be implemented, tested, and documented • Living Documents - need to be updated as the project evolves to reflect changes and new insights Sprint Planning and Retrospectives: • Documentation Tasks - documentation is part of the Definition of Done (DoD) for each story or task • Review and Improve - Use retros to review the quality of the documentation and identify areas for improvement Collaborative Documentation • Pair Writing - developers and technical writers collaborate to produce and refine docs • Shared Ownership - make docs a shared responsibility, with contributions from all team members. Continuous Integration and Delivery (CI/CD) • Automated Documentation Generation - Use tools to automatically generate and update doc from code comments and annotations as part of the CI/CD pipeline • Documentation Reviews: Integrate documentation review as part of the CI/ CD process, ensuring that docs are kept up-to-date with the latest code changes
Static Site Generators • Markdown: Simple syntax for writing documentation, which can be easily converted into various formats • Static Site Generators: Tools like Jekyll, Hugo, and MkDocs can generate static websites from .md files, making docs easily accessible and navigable Version Control Integration • Git: Use Git to manage and version docs alongside code, ensuring that docs changes are tracked and can be reviewed • GitHub Pages: Host docs directly from a GitHub repo using GitHub Pages Collaborative Documentation Tools • Confluence: tool for collaborative docs that integrates well with other Atlassian products like Jira • Notion: A flexible tool for creating and organizing docs, wikis, and collaborative notes Code Documentation Tools • Javadoc/Doxygen: Tools for generating API docs from code comments in languages like Java and C++ • Sphinx: A docs generator for Python projects IDE Plugins • Live Preview Plugins: Plugins that provide live previews of Markdown or other docs formats directly within the IDE • Linting Tools: Plugins that check docs for spelling, grammar, and style issues to ensure high-quality docs
that helps clarify the purpose and function of a project • The act of documenting involves • Capturing in a structured format • Important information • Instructions • Guidelines • Explanations • Making it accessible to others, including • Team members • Stakeholders • End-users
– hours of thinking and planning can save up weeks of coding • Make writing down what you decide transparent in an architecture decision log • Explain purpose, goals, constraints as you experience them • Too often “later” becomes “never” • Docs are working documents, which live and breathe and serve you and others – without them, you create technical debt.
cleyra
erikaheidi
danielanewman
mongodb
aki_iinuma
bcantrill
sergeychernyshev
denniskardys
thekraken
eileencodes
bkeepers
holman
