Documentation we Typically Provide from Project Completion to Being Live

Core Question: After design and development work is completed, please describe or define the software documentation you provide back to your clients?

As an agency that works with two primary types of client teams, we have catered standards that help to streamline the documentation that gets created as part of a development heavy project or MVP.

With regards to documentation relating to other developers jumping into the codebase / project we provide root level documents and instructions on how to use and deploy the application. Within the code itself we put comments next to each critical component, helping to explain what is being done and why it exists.

With regards to documentation from a “training” or system usage for non-technical users we cater to the client and team needs (i.e. how to utilize the CMS to alter content needs, create pages, etc.). Typically it involves a gradual training schedule whereby you and your team are learning how the system operates and how to use it as development goes along. This is often complemented with a training manual that helps to address what type of user permission we are describing out actions for and what use cases they are needing to learn the system in preparation for. This would output as a PDF document.

Tony: So after design and development is done, you know, we finished a project, we’re all feeling good, please describe or define I guess the documentation we typically provide to clients.  What does that transition over from project completion and potentially launch to it being out in the world look like? 

Jake: My hope is that the client understands the project before it’s completed.  I don’t want to all of a sudden get to the end and they’re like, okay, teach me how this works now.  The goal is that you’re learning as the client either each week, you know, every other week, exactly what’s happening, so that when we get to the end there shouldn’t be any surprises, and as we’re going and modeling things, it should be based off your business cases.  But as far as documentation goes, and other developers hopping in, we try to follow best practices and standards around documentation. Typically in the root of the project there is a general description of like, this is what the project is, this is what we use, this is why we use it, this is how you get it set up, and this is how it gets deployed, all these great things.  And then as far as more specific code things, we add little pieces of documentation right next to the functions that we’re writing, so that you know a little bit more about that function, but more importantly it’s why that function is there, rather than what it’s doing.  

Tony: Okay, yeah, and definitely on the other side it could be perceived as the training aspect.  Obviously CMS managing content, being a big component of a project and I guess the majority of people that will touch it, it’s making sure that is detailed out, they know how to use it before it launches, not “hey, we’re about to launch, how do I change this on a page, or how do I do this?”  So obviously that plays into a huge part of just communicating, getting docs in front of them, manuals, and learning again how they like to learn the best. Because if you do an in person 4-hour, 8-hour, whatever it is, training session and people aren’t paying attention or that’s not the way they learn, then all of a sudden one week later they go, “oh, I forgot how to do it because I wasn’t paying attention.”  So, sometimes that might mean actually making little tutorials or PDFs, or putting in-site documentation and learning maybe where their weak points are and where they excel at absorbing that information.

Jake: Absolutely, as far as the developer perspective, I try to look at it as it’s effective if within the first week I’m able to onboard a new person and that person is able to contribute back to the project.  If we’re able to do those things, chances are we did pretty well with the documentation, so we even try that sometimes with our own team members as we’re trying to bring people on. So even as we go throughout the process, that’s being tested.