Download as PDF, PPTX
Uploaded byÓlafur Andri Ragnarsson
L16 Documenting Software
The document discusses the importance of software documentation and provides guidelines for an effective software guidebook. It recommends that a software guidebook include sections on context, functional overview, quality attributes, constraints, principles, software architecture, external interfaces, code, data, and infrastructure architecture. The guidebook should provide concise, clear explanations to help new developers understand the overall structure and design of the software without being overly detailed. Maintaining up-to-date yet concise documentation is important for onboarding new team members and communicating design decisions.
More Related Content
Similar to L16 Documenting Software
L16 Documenting Software
- 1. HÖNNUN OG SMÍÐIHUGBÚNAÐAR 2015 L16 Documenting Software
- 2.
- 3.
- 4.
- 5. Common belief: Commentsare bad and get outdated, just strive for writing self-documenting code Yes, we should aim for that, but the code does not tell the whole story Why documentation?
- 6. If you arenew to an ongoing software project, where do you start? Still you need to know a lot of things: • What is the overall architecture? • Are there naming conventions? • What design principles are in place? • How is the layering? • What frameworks? • etc… Why documentation?
- 7. The code doesnot portray the intent of the design Perhaps it is easy to understand what the software does on a high-level, but we still need to understand: • How does the system fit in the existing landscape • Why the technologies were chosen • Overall structure • Interconnections between subsystems • Logging strategy • Design patterns • etc… Why documentation?
- 8.
- 9.
- 10. “Working software overcomprehensive documentation” - The Agile Manifesto For many this means: no documentation How can complex enterprise software need no documentation, when a $20 toaster has one Practical experience says that there are things that need explanation, a guidebook Documentation Guidebook
- 11. Problem is thatdevelopers on a software team think documentation is writing Microsoft Word documents and UML software - all of which get outdates fast And who will read such outdated material? Documentation Guidebook
- 12. Navigating from Detailto Big Picture Maps help you navigate foreign countries If you get dropped in a place you need to “zoom out” to see the whole picture Visualising software with the C4 approach
- 13. Navigating from Detailto Big Picture Sights help you understand the nature of the country The codebase is to large to go though but if you know where the interesting parts are, it will help For example, you might look at one Input Controller and how it connects to the model and the view - you don’t need to look at the other hundred or so since you know get it
- 14. Navigating from Detailto Big Picture History and culture help you understand the people and their ways of doing things and why It helps if you know the motivation and reasons why the software is like it is You get a lot of understanding if you know the motivations and preferences of the people that are working on the software
- 15. Navigating from Detailto Big Picture Practical information such as currency, power outlets, laws, customs etc help you You need to how where the codebase is, what tools to install, the URL to stuff and so on It’s all the stuff that can help the development team to do their job effectively
- 16. Keep it short,keep it simple Since the code doesn’t tell the whole story, some supplementary documentation is needed This documentation can be thought of as a guidebook Should contain enough information but not too much detail as these are the things that change and the story the code tells anyways Consise, to the point text is need
- 17. Beware of the“views” Some documentation emphasis showing diffrent view like the “logical view” and “physical view” etc. These are fine, but tend to very confusing and make people hate documentation (as if that was hard) Better approach is to write clear, no bullshit, like it is documentation
- 18. Product vs. ProjectDocumentation Projects are temporary undertakings that are timeboxed, products last many projects Project documentation should specify what is needed to make the project succeed and gets outdates when the project is over Product documentation should specify how the product works at any time
- 19. Software Guidebook These sectionsmight be in such a guidebook: Context Functional Overiew Quality Attributes Constraints Principles Software Architecture External Interfaces Code Data Infrastructure Architecture Deployment Operation and Support Decision Log
- 20. Context A context sectionis one of the first sections and should set the scene for the rest of the document Intent Should answer the following questions: •What is the software product all about? •What is it that’s being built? •How does it fit into the existing environment? •Who is using it? Structure Does not need to be long, 1-2 pages with context diagram
- 21. Context A context sectionis one of the first sections and should set the scene for the rest of the document Motivation Give the readers the overview so they know what is to follow Audience Technical and non-technical, inside or outside the team
- 22. Functional Overview Expand onthe context and summarise the major function of the software Intent Summarise the key functions, should make clear: • What the system actually does • Features, functions, user stories etc are • Who the users are • How this shapes and defines the architecture Structure This acts as a summary of functionality and shows the most defining functions without replacing the actual detailed users stories
- 23. Motivation Should notbe long but should show what the system actually does where the context shows where it fits in Audience Technical and non-technical, inside or outside the team Functional Overview Expand on the context and summarise the major function of the software
- 24. Quality Attributes Specifies thenon-functional attributes of the system Intent Should specify the quality attributes • Performance, uptime etc • Realistic and measurable not some fancy words • Things that are granted should be stated • Any unrealistic attributes should be address Structure Listing such as performance, scalability, availability, security, extensibility, flexibility, monitoring, disaster recovery etc… “System should be fast” is unacceptable
- 25. Motivation Putting thisin writing removes any ambiguity Audience Technical people mostly Quality Attributes Specifies the non-functional attributes of the system Required Yes
- 26. Contraints Software system alwayshave contraints. This section should document those. Intent Should explicitly summarise the constraints that the team is working within, and all the decisions that have been made for you Structure Listing such time, budget and resource, approved technology, deployment platform, existing system, localisation, protocols allowed, legal requirements etc.
- 27. Motivation Contraints massivelyinfluence architecture Audience Everybody involved in the development process as some constraints are not technical Required Yes Contraints Software system always have contraints. This section should document those.
- 28. Principles Summary of theprinciples used to design and build the software Intent Principles that are important need to be specified to be adopt and followed Structure Listing such Layering, no logic in the view, no logic in the database, use ORM, use Dependancy Injection, follow SOLID, DRY etc.
- 29. Motivation Since principleshelp consistency and ensure that common problems are solved in the same way, it is important tok make them explicit so everyone on the team understands what they are Audience Development Team Required Yes Principles Summary of the principles used to design and build the software
- 30. Software Architecture This isthe “big picture” and allows you to show the structure of the software Intent Summary of the software architecture should answer these questions: • What is the big picture • What is the structure, major containers, components and interactions • etc… Structure Container and component diagrams with short narrative of what the diagrams are showing
- 31. Motivation This isthe map that will guide you Audience Development Team Required Yes Software Architecture This is the “big picture” and allows you to show the structure of the software
- 32. External Interfaces Interfaces withexternal systems is the riskiest part of the software and needs to be summarised Intent Summary of key interfaces, technical and non- technical perspective Structure List of external interfaces, with component diagrams, and information on where to find documentation, and who is responsible on both ends
- 33. Motivation This needto be covered since it is easily underestimated but contains a lot of risk Audience Development Team Required Only if there are risky interfaces External Interfaces Interfaces with external systems is the riskiest part of the software and needs to be summarised
- 34. Code This sections presentsa lower level explanation on how things work Intent Describe in detail how important and complex things in the software work, for example MVC, application life-cycle management, state handing etc. Structure Short, concise sections, aided with diagrams, that explain each topic
- 35. Motivation Ensure thateverybody on the team understands complex things about the software Audience Development Team Required No, but most software needs this Code This sections presents a lower level explanation on how things work
- 36. Data Record data isimportant in enterprise systems and the data strategy needs to be clarified Intent Explain the data model, how it is stored and where, what are backup storage and redundancy strategies etc. Structure Short, concise sections, aided with diagrams, that explain the data strategy
- 37. Motivation Data tendsto outlive the software, so it is necessary to explain the strategy Audience Development Team Required No, but most software with data needs this Data Record data is important in enterprise systems and the data strategy needs to be clarified
- 38. Infrastructure Architecture Infrastructure isa big part of software since software needs to be stored and operated in a physical hardware environment Intent Outline the physical setup, hardware, use of virtualisation, redundancy, failover, load balancers etc. Structure Network diagrams with explanations
- 39. Motivation Software mustbe run somewhere in a physical setup and this explains how the setup is Audience Technical people, network operators Required Yes Infrastructure Architecture Infrastructure is a big part of software since software needs to be stored and operated in a physical hardware environment
- 40. Deployment Deployment explains howsoftware is installed on the hardware Intent Describe the mapping of software and the hardware, how and where software is installed and configured Structure Tables showing mapping and deployment diagrams with explanation
- 41. Motivation Gives understandingon how the software will actually work when running Today you want to automate this things as much as possible with tools such as Puppet and Chef Audience Technical people, network operators Required Yes Deployment Deployment explains how software is installed on the hardware
- 42. Operation and Support Describeshow people will monitor, run and manage the software Intent How monitoring and managing the system is done, where the log files are, configurations, manual housekeeping stuff etc Structure Narrative explaining each topic
- 43. Motivation How tooperate the software must be documented, all file locations and so on Audience Technical people, network operators Required Yes Operation and Support Describes how people will monitor, run and manage the software
- 44. Decision Log Log ofdecision made during the development phase Intent Document for reference any major decision and the reason for them, why some technology was chosen and so on Structure Simple list of decisions
- 45. Motivation Software developmentis complex and major decision are made for reasons, but can be forgotten People tend to avoid responsibility so keeping track of decision and their reasons can save a lot of discussion later Audience Technical people, operation Required No, but really useful Decision Log Log of decision made during the development phase
- 46. Summary Yes, we needdocumentation, the code does not say it all and agile does not gives us excuses Software Guidebook is a really useful tool
- 47.