Web Development Technical Documentation PDF

Lesson 11: WEB DEVELOPMENT TECHNICAL DOCUMENTATION TOPIC OUTLINE Technical Documentation, System Flows and Diagrams Different Diagrams and Flowcharts for Web Development  What is Technical Documentation? Technical documentation in software engineering is the...

Lesson 11: WEB DEVELOPMENT TECHNICAL DOCUMENTATION TOPIC OUTLINE Technical Documentation, System Flows and Diagrams Different Diagrams and Flowcharts for Web Development  What is Technical Documentation? Technical documentation in software engineering is the umbrella term that encompasses all written documents and materials related to software product development. All software solutions, whether created by a small team or a large corporation, require various types of documents throughout the whole software development lifecycle (SDLC). TECHNICAL DOCUMENTATION IN SOFTWARE DEVELOPMENT TECHNICAL DOCUMENTATION IN SOFTWARE DEVELOPMENT AGILE AND WATERFALL APPROACH  Waterfall approach The Waterfall approach is a linear method in which you can only proceed to the next stage when you finish the previous one. Teams that use waterfall spend a reasonable amount of time on product planning in the early stages of the project. They create an extensive overview of the main goals and objectives and plan in detail what the working process will look like. Waterfall approach to software documentation  Waterfall approach The Waterfall approach is a linear method in which you can only proceed to the next stage when you finish the previous one. Teams that use waterfall spend a reasonable amount of time on product planning in the early stages of the project. They create an extensive overview of the main goals and objectives and plan in detail what the working process will look like. Waterfall approach to software documentation  Agile approach The Agile approach is based on teamwork, close collaboration between developers, business stakeholders, and end customers, flexibility, and the ability to quickly respond to changes. The basic building blocks of Agile development are iterations: Each of them includes such stages as planning, design, development, etc. The project revolves around to fix issues and produce a better product Agile approach to software documentation  Agile approach The Agile approach is based on teamwork, close collaboration between developers, business stakeholders, and end customers, flexibility, and the ability to quickly respond to changes. The basic building blocks of Agile development are iterations: Each of them includes such stages as planning, design, development, et Agile approach to software documentation  Agile approach The Agile approach is based on teamwork, close collaboration between developers, business stakeholders, and end customers, flexibility, and the ability to quickly respond to changes. The basic building blocks of Agile development are iterations: Each of them includes such stages as planning, design, development, et Agile approach to software documentation TYPES OF TECHNICAL DOCUMENTATION Software documentation can be divided into two main categories: Product Documentation - System Documentation - User Documentation Process Documentation Process documentation Describes how teams work when developing software. It’s like a detailed guidebook that lists the procedures team members follow during the SDLC, the tools they use, and the rules they must adhere to. This documentation helps everyone understand how things are done, ensures that the process is consistent, and makes it easier for new team members to get up to speed. Common examples of process-related documents are backlogs, roadmaps, coding and testing standards, reports, meeting notes, release checklists, and even business correspondence. Product documentation Describes the solution that is being developed and provides instructions on how to interact with it. In general, product documentation includes requirements, tech specifications, business logic, and manuals. There are two main types of product documentation: - System documentation describes the system itself and its parts. It includes requirements documents, design decisions, architecture descriptions, program source code, etc. - User documentation covers manuals mainly prepared for product end-users and system administrators. It includes tutorials, user guides, troubleshooting manuals, installation instructions, and so on. Product documentation A product requirements document or PRD provides information about system functionality and behavior. Generally, requirements are statements of what a system should do and how it should work. Product documentation example: Main Points to PRD - Roles and responsibilities. Start with information about project participants, including a product owner, team members, and other key stakeholders. These details will clarify responsibilities and communicate the roles of each team member. - Team goals and business objectives. Briefly define the most important goals of the project. - User interaction and design. Often, the exact design is created after composing the PRD, so you can just include general guidance or rough sketches of the product design. Later, when actual designs are available, you can link them to the PRD. - Assumptions. Create a list of technical or business assumptions that you plan to validate or invalidate during the project. - User stories. List or link user stories that are required for the project. Written from the end user’s point of view, a user story is a short description of customer actions and the results they want to achieve. - Acceptance criteria. Those are the conditions that indicate a user story is completed. The main purpose of UX design documentation. User experience design (UX design) begins at the planning stage and proceeds through all the stages of development, including the testing and post-release stages. The process of UX design includes research, prototyping, usability testing, and the actual designing phase, during which lots of documentation and deliverables are produced. It focuses on these 3: -user personas -user scenario -scenario maps UX design documentation -User personas represent the key characteristics of potential product users, focusing on behavior, thought patterns, and motivation. They help define customer segments and tailor the product functionality and future marketing strategies to different user groups. -A user scenario is a document that describes the steps a user persona will take to accomplish a specific task. User scenarios focus on what a user will do, rather than outlining the thought process. -Scenario maps are used to compile the existing user scenarios into a single document. Scenario maps show all possible scenarios available at a given moment for every single function, as well as intersecting scenario steps. Scenario Maps -A site/product map is a visual scheme that represents the connection between all pages of a product. It helps the team visualize the structure of a website or app and the connections between the pages/functions. Creating a site map is a part of arranging the information architecture. -User flow or user journey maps visualize the steps a user should take while interacting with all parts of the product. Usually, the scheme includes all the pages, sections, buttons, and provided functions to show the logic of user movement. -Wireframes are the blueprints for future UI. Basically, wireframes are schemes that show how to arrange the elements on the page and how they should behave, but without details of how those elements should look. Site map example: -User personas represent the key characteristics of potential product users, focusing on behavior, thought patterns, and motivation. They help define customer segments and tailor the product functionality and future marketing strategies to different user groups. -A user scenario is a document that describes the steps a user persona will take to accomplish a specific task. User scenarios focus on what a user will do, rather than outlining the thought process. -Scenario maps are used to compile the existing user scenarios into a single document. Scenario maps show all possible scenarios available at a given moment for every single function, as well as intersecting scenario steps. User Flow example: Wireframe example: Prototyping Mock-ups, the next step of the design creation, are static images representing the actual look and feel of a final product. A prototype is a mock-up that you can interact with: click some buttons, navigate between different pages, and so on. A prototype can be created in a prototyping tool like Sketch or MockFlow. Using templates, UX designers can create interactive mock-ups in the early stages of development to be employed for usability testing. Technical Design Document A technical design document (TDD), also often referred to as technical specification, provides detailed, low-level information on how a software system's requirements are to be implemented. It bridges the gap between system architecture and the actual codebase, detailing the specific configurations, interfaces, and coding standards that developers will follow. A TDD includes component designs, data flow diagrams, algorithms, API endpoints, and interaction protocols, ensuring that developers have a clear and precise guide for building the software. Source code documentation Source code documentation is a type of technical documentation embedded directly within the solution’s source code. It explains what the code does, how it works, and why certain decisions were made. This can include descriptions of algorithms, configurations, and complex logic. Source code documentation comes in the form of comments that can range from single-line notes explaining a particular operation to bigger, block explanations describing more complex logic or data structures. Technical Design Document A technical design document (TDD), also often referred to as technical specification, provides detailed, low-level information on how a software system's requirements are to be implemented. It bridges the gap between system architecture and the actual codebase, detailing the specific configurations, interfaces, and coding standards that developers will follow. A TDD includes component designs, data flow diagrams, algorithms, API endpoints, and interaction protocols, ensuring that developers have a clear and precise guide for building the software. Quality Assurance Documentation Quality management plan - an analog of a requirement document dedicated to testing. Test plan - a detailed document that outlines the objectives, resources, scope, and schedule of intended testing activities in a project. Test case specifications - a set of detailed actions to verify each feature or functionality of a product. Test checklists - a list of tests that should be run at a particular time. API Documentation Most products include APIs (Application Programming Interfaces) to enable data exchange with other systems. API documentation contains a list of all product APIs and their specs. It describes requests, responses, error messages, and other essential details, and informs developers how to effectively interact with the system APIs. Assignment (December 12, 2024 – 430PM) Your task is to conceptualize and design the foundational structure of a web development product (e.g., a blog site, e-commerce platform, portfolio website, or online learning platform). You will complete the following deliverables: User Flow Diagram Create a visual representation of how a typical user will navigate through your web product. Consider different user goals and key interactions, ensuring the flow is intuitive and seamless. Site Map Design a comprehensive site map illustrating the hierarchical structure of your website. This should include main pages, subpages, and connections between them. Wireframes/Prototype Develop low-fidelity wireframes for at least three key screens of your website. Focus on the layout, placement of elements, and user interface components. Figma is required for this documentation/document Explain how you planned the user persona and user preferences to develop your Scenario maps. REFERENCES https://www.geeksforgeeks.org/requirements-gathering-introduction-processes-benefits-and-tools/#what-is- requirements-gathering https://www.geeksforgeeks.org/agile-software-development-methodology-framework/?ref=oin_asr8 https://youtu.be/mm8sTgoUhRY https://youtu.be/MY8pQviEt6U https://www.altexsoft.com/blog/technical-documentation-in-software-development-types-best-practices-and- tools/