Software Documentation at ScienceSoft

Why We Treat Software Documentation Seriously

Throughout the projects we partake in, our experts prepare all necessary process and software documentation and consistently share it internally and with our clients. Clear and up-to-date software documents help us avoid misunderstandings between the project stakeholders and guarantee the development service alignment with our clients’ needs. Timely and exhaustive documentation contributes to higher teamwork efficiency, improves project predictability, and streamlines software evolution and support.

Poor Software Documentation Practices We Avoid

Much like technical debt, the damage from poor-quality and missing software documents is cumulative and propagates to all major IT process and solution KPIs over time. In particular, the lack of appropriate documentation results in opaque development flows, hampers effective change management, and complicates troubleshooting, ultimately leading to a higher software TCO.

ScienceSoft’s Approach to Software Documentation

Documents We Deliver at Every Stage of Software Development

Software development initiatives vary significantly in terms of goals, deliverables, and implementation flows, so the scope of documents differs for each project. Below, we share a comprehensive list of documents we commonly deliver across various software development project stages, complete with practical examples.

1. Discovery stage

The documents we deliver during the discovery stage serve to make sure our project vision and development capacities fully align with our client’s requirements:

• A project charter provides a high-level project description. It helps stakeholders gain a shared understanding of the project goals, objectives, and requirements before the project is scoped out in detail. ScienceSoft's project charter covers a stakeholder matrix and a communication plan. This way, we ensure everyone is on the same page regarding the responsibilities and role-specific development aspects.

• A high-level solution scope and vision reflects our assumptions on how the software and development process should work. It includes a high-level project plan, a task scope, a map of the solution’s major functional capabilities, and a general overview of the solution’s technical design.

• Discovery estimates provide the customer with an idea of the expected project cost.
• A quality strategy states ScienceSoft’s approach to quality management throughout the SDLC: it includes a service KPI system, a customer data protection policy, collaboration principles, and more.

2. Solution design

The artifacts we deliver at this stage ensure the client’s stakeholders are aware of and agree with the technical design decisions that affect the capabilities, visual style, maintainability, and OpEx of future software. If there are any concerns, we promptly investigate them and make the necessary fixes.

• A business requirements specification overviews our customer’s business goals, needs, risks, and success metrics. If needed, it also covers region-specific regulatory compliance requirements.
• Technical requirements specifications describe the product's desired functional and non-functional behavior (can be presented as user stories, mockup-based behavior descriptions, etc.).

• An architecture design depicts the interactions between the solution components, the integrations with external systems (databases, business-critical software, third-party services), and user and data access points.

• User journey maps showcase the steps software users perform to achieve their goals.

• UX wireframes demonstrate the application pages' layout (visual structure, content, and functionality).

• A UI kit contains critical visual design components like layered design files, fonts, icons, buttons, and HTML/CSS files.

• A list of technologies and tools describes every tech component we plan to use for software development.

3. Project planning

A finalized technical design helps accurately plan and estimate the project. The documents our clients receive at this stage provide a detailed vision of the time-framed development flow, roles, deliverables, and success measures to control the project progress and efficiency:

• A project roadmap with a work breakdown structure and milestones.

• A team structure specification that includes detailed profiles of our developers, QA specialists, and other talents involved in the development process (e.g., data scientists, cybersecurity experts).
• Cost and time estimates bound to particular development tasks.
• Process KPI documentation to track the project progress and team’s performance.
• A quality assurance plan that describes the test strategy, major testing activities, acceptance criteria and mechanisms, and QA team composition.
• A risk mitigation plan listing the potential development and solution risks and our actions to prevent them.

NB: Waterfall development of standardized software with known capabilities (e.g., a corporate website) doesn’t require extensive discovery. In this scenario, we provide the customer with a detailed project plan instead of a vision and scope document at the beginning of our cooperation and proceed with the software technical design.

4. Coding and quality assurance

ScienceSoft’s teams typically run the necessary testing procedures in parallel with coding to promptly detect and fix the issues and speed up releases. The major documents we deliver during this stage are:

• A test plan containing a detailed list of planned testing activities, test cases or checklists, and test data sets (delivered in case of collaborative QA).
• Test reports describing the testing progress, defects validation results, and invested efforts.

• Regression testing summary reports to make sure the software adjustments and upgrades haven't broken any existing functionality.
• A security audit report describing the security assessment results for software under development. It is necessary for solutions with high requirements for sensitive data protection (e.g., medical software, lending systems, payment smart contracts).

5. Software delivery to the customer

The documents we provide at this stage enable smooth software deployment, maintenance, and evolution. They also help the end users easily operate the app, which reduces the burden on the customer’s IT support team and contributes to higher software adoption rates.

• Documented source code with README files and developers’ comments.
• OpenAPI-compliant API documentation containing instructions on how to integrate with the API and effectively use its services. Our experts create API documentation using Swagger so that our clients can instantly validate the correct API work.
• A configuration guide for software hosting providers and app/system administrators to configure the hosting environment, deploy the solution to prod, set certificates, encryptions, system protections, backup and recovery procedures. We typically use a single repository for the source code and configuration guides to streamline documentation accessibility and maintenance.

• A maintenance guide describing the activities needed to support and upgrade the software components and infrastructure, ensuring its full security and compliance.
• Manuals, tutorials, and how-to guides for end users to help them quickly learn how to use the software and promptly find solutions to any issues.

6. After-launch support

We back our support and evolution activities with the relevant documentation to ensure the software operates smoothly, and its later updates don’t pose any operational risks.

• Release notes to keep the software users up to date about the new and changed features.
• Regular KPI-based maintenance reports on the important metrics across software performance, availability, and security. They help control the solution's health and our IT support team’s compliance with service-level objectives.
• (If we performed an independent audit of an existing solution) System audit and code review reports describing the revealed issues, their potential short- and long-term impact, and optimal ways to fix the flaws.