Software Planning and Technical Documentation

he's really putting you to work huh did you want to develop an app i'll pass clooty you're lost oh yeah why is that that's an app you'd want to develop can i ask what it is of course you can that's always the first step in app development in this episode of rick and morty jerry falls into a trap by agreeing to develop an app he knows nothing about the app is launched shortly and the world faces the consequences this is not something we have to worry about in real life but the show is parodying an

actual startup phenomenon the culture of hatching new products without much planning or preparation driven by excitement and the hope for success software development is never as easy as on rick and morty since presumably you don't have an alien on the team it's an expensive time-consuming and risky endeavor to have a chance at success you need clear communication elaborate planning and documented expectations how does this planning happen and what helps devs stay on course let's talk about software planning and technical documentation luckily if you're building software you're not the first one to do that and even

if you were you wouldn't be the first one to build something there are many parallels between software development and construction reflected not only in the wording but also in methods project management itself until very recently was a discipline associated with civil engineering and manufacturing that's why in continuation of the practice for many decades software products were built like tangible ones look at the now discredited waterfall model according to it the project should follow a few consecutive steps gathering product requirements preparing the design then implementing said design doing some testing and finally performing maintenance and system

support this approach seemed logical because software was treated like buildings or ships or any big construction projects where you do massive amounts of work first and then apply changes where needed this of course led to failed deadlines overgrown teams and thousands of lines of code rewritten over and over again only very recently 20 years ago to be more exact this thinking has changed the agile manifesto questioned the traditional approach and brought the new idea building software is an ongoing endeavor where planning should happen along with execution and testing today we enjoy how the agile principles

help us lower risk and always have the ability to change something if needed this is mostly accomplished thanks to great documentation which just like any other element of agile project management is subject to change through as many iterations as needed so what documents are used in software planning software planning is in many ways synonymous with software documentation because technical docs is where software starts taking shape it's where the idea of a ride sharing app becomes a complex system with its business logic text specifications and user flows and where we first determine the path to this

transformation ultimately docs help us answer two big questions first what should the product be like this part of project management is described in product documentation the second question is how are we going to build this product it's covered in process documentation strap in as we dive deeper into both these groups and we'll start with the what question a product is a system with a set of features that helps users achieve their goals in software development these features are called functional requirements and the properties this system should have are the non-functional requirements both are expected by

a stakeholder or an end user to fulfill the product's main purpose a user should be able to check the order status on the main screen is a functional requirement that talks about user capabilities a system must support one hundred thousand users at the same time is a non-functional requirement because it describes the capabilities of the product how fast it is what security measures it uses how the system must grow such concise statements translate user and stakeholder desires into requirements that developers understand and can then plan to implement a product requirement document is one of the

first created requirements are largely dictated by users they're basically the result of all the user research done earlier when the team talked to real life people and learned about their preferences and experiences this research though results not only in the feature list but in other invaluable pieces of information for example in user personas a persona is a detailed description of a typical user that makes it easier for the dev team to visualize what the people want need and how they behave the behavior of a persona is then broken down into user scenarios about people accomplishing

a task often represented in comic strip form scenarios help designers understand a future user's thought process and motivation scenarios are broken down even further into specific user stories that look very similar to end features a user story is written from the point of view of a user persona and looks something like this as a busy manager i want to receive automated reports so that i'm always up to date with metrics or as a parent i want to control what content my kids are watching to keep them safe these user research docs help compile deliverables more

documentation with product prototypes wireframes and user journey maps these describe the future and many testing iterations later final user experience okay so we describe the features and the product design time to talk about technology one of the first technical decisions a team has to make is a product's architecture although the main three architecture layers apply to most applications many products require complex custom architectures and these design choices are described and visualized by a software architect architecture depictions are usually pretty schematic but they communicate to the team what components and design principles should be used without

many tech details what should be pretty technical is a testing plan in agile development testing happens along with engineering not after and if you're using a popular approach called test driven development you'd be writing test cases based on requirements before you even start any serious development work if you've seen our video on qa you should know that test cases are detailed descriptions of what features should be tested and how step by step all test cases make up the test plan which gives some time frames and assigns roles to qa engineers and developers in this process

so let's recap all this time we've been talking about product planning requirements ux architecture and testing strategy being some of the first documents created in preparation for development to tell the team what type of product they will be building but we also need to document how it should be built with all its processes organized around the product not surprisingly this branch of work is called process documentation the father of project management henry gantt created his famous gantt chart more than a century ago and in the agile era it's still one of our favorite planning tools

most product roadmaps are based on the gantt design that's how software devs list their objectives prioritize tasks and assign deadlines there's a strategy roadmap with high level goals and rough delivery estimates it shouldn't be detailed because you need to view the whole project on a single screen then we go low level with the technology roadmap which lists the smallest deliverables and their due dates finally a release roadmap has strict deadlines for when each part of the project should start functioning and what features go live when apart from the schedule process documentation includes metrics and standards

project metrics are meant to provide regular feedback on how fast and effective the work is metrics are the main tools of the agile development process that help spot any bottlenecks and problems in the code quality before they proliferate and stall the whole project similarly standards and guidelines both for coding and ux people set up best practices that every team member regardless of when they join the project or what their experience is can use to create consistent code and design now you may have looked at the whole scope of document creation and wondered what's agile about

that you won't be the first to ask that question why do so much planning if the idea is to check your hypotheses fast and move on to the next one well there are a few reasons first is despite how flexible the agile processes are meant to be they only work that well because of great organization you don't have to be certain about the task but you need to know the scope of it what it affects and what complications may arise but some mistakes can and should be prevented rather than embraced in the process for example

even though user testing is conducted throughout the development journey you don't want to start working on features before you do user research here overpreparation will save you time and money and finally written documentation remains the best communication tool for big groups and projects this is how your new devs will learn the project details and the old ones will remember them this is your main source of truth in case of conflict and this approach makes it easier to access information rather than asking someone or doing research that's already been done stay tuned as we continue this

topic with a series of videos on technical documentation let us know in the comments what you want to learn from our future explainers [Music] you