L16 Documenting Software

  • View
    361

  • Download
    0

Embed Size (px)

Transcript

  • HNNUN OG SMI HUGBNAAR 2015L16 Documenting Software

  • Agenda

    Why documentationSoftware Guidebook

  • Reading

    Brown textbook 48-63

  • Why documentation?

  • Common belief: Comments are 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?

  • If you are new 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?

  • The code does not 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?

  • Why documentation?

  • Documentation Guidebook

  • Working software over comprehensive 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

  • Problem is that developers 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

  • Navigating from Detail to 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

  • Navigating from Detail to 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 dont need to look at the other hundred or so since you know get it

  • Navigating from Detail to 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

  • Navigating from Detail to 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

    Its all the stuff that can help the development team to do their job effectively

  • Keep it short, keep it simple

    Since the code doesnt 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

  • 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

  • Product vs. Project Documentation

    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

  • Software Guidebook

    These sections might 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

  • ContextA context section is 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 thats 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

  • ContextA context section is 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

  • Functional OverviewExpand on the 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

  • Motivation Should not be 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 OverviewExpand on the context and summarise the major function of the software

  • Quality AttributesSpecifies the non-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

  • Motivation Putting this in writing removes any ambiguity

    Audience Technical people mostly

    Quality AttributesSpecifies the non-functional attributes of the system

    Required Yes

  • ContraintsSoftware system always have 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.

  • Motivation Contraints massively influence architecture

    Audience Everybody involved in the development process as some constraints are not technical

    Required Yes

    ContraintsSoftware system always have contraints. This section should document those.

  • PrinciplesSummary of the principles 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.

  • Motivation Since principles help 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

    PrinciplesSummary of the principles used to design and build the software

  • Software ArchitectureThis is the 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

  • Motivation This is the map that will guide you

    Audience Development Team

    Required Yes

    Software ArchitectureThis is the big picture and allows you to show the structure of the software

  • External InterfacesInterfaces with external 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

  • Motivation This need to be covered since it is easily underestimated but contains a lot of risk

    Audience Development Team

    Required Only if there are risky interfaces

    External InterfacesInterfaces with external systems is the riskiest part of the software and needs to be summarised

  • CodeThis sections presents a 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

  • Motivation Ensure that everybody on the team understands complex things about the software

    Audience Development Team

    Required No, but most software needs this

    CodeThis sections presents a lower level explanation on how things work

  • DataRecord data is important 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,