How to Document Front End Software Products

In the industry of software products, it can be really challenging for engineers to obtain documentation from Product Owners that can actually be used to build and test a product. Product Owners are not Engineers, and are often not what we, as Engineers, would classify as “technical”, so they have very little concept of what information an Engineer needs in order to actually compose a functional digital product. This means that it often falls to engineers and technical leadership to build and maintain a library of documentation for the products they’re building. Here are some tips for writing quality documentation that can be used as both a tool for building a product, and a reference for learning and testing how software works.

1. Write Documentation

The first step to writing great documentation is… writing anything at all. Often times, even in huge corporation, there is no consolidated source of truth that outlines how things are supposed to work. If you don’t even know how something is supposed to work, you can’t have much confidence that it’s working correctly. Even more frequently, the source of product requirements is a user story or feature ticket that a product owner or business analyst created for engineers to plan the work. This is not documentation. Transient tickets in a tools like JIRA or Rally that you might use to plan and track work can easily be lost or abandoned once work is done. It’s worth composing additional, long-lived documentation that says how things should function. When the code is the only source of documentation, the code can’t ever be wrong. Even when it is.

2. Use Visual Aids

Product Requirements often involve a specialized vernacular that, ironically, isn’t well suited for use in actually building a product. That’s because these requirements may have a different set of goals then what’s needed for engineering level documentation, i.e. business logic, future planning and legal requirements. That means that Product Requirements regularly need to be translated into something that’s better suited as a description of software functionality. The best way to do this is to simply map the designs to the data. That is, capture a screenshot of each screen, and outline how each piece of dynamic data on the screen is sourced or calculated. For example, here’s a screen shot of an inventory application, with some annotated notes about how the screen works:

Product Detail Screen

The Product Detail screen uses the /product/{productId}/details API. A GET call to the API retrieves the current details, and a POST updates them.

The “Product Name” EditText should use the name field value from the GET response payload.

The “Price” EditText should use the amount field value.

The “Quantity” EditText should use the inventory field value

The “Order More” button, when clicked should launch the Product Order screen, using the id field value.

The “Save” button should call the Product Details POST API.

If you compose documents as the example shows, any developer on any platform should be able to read it and understand the logic, and then know how to build and test their code. It’s also a great idea to include a link to an example API payload JSON, or include one in the document.

3. Keep It Up-to-Date

Documentation is only as valuable as it is accurate, so it’s important to keep your documentation in sync with changes to the UI and the backend services. It’s excellent practice to make updating the documentation part of the development work, so that dev tasks can’t be marked complete until the docs are also updated (and If you use JIRA, it’s an even better idea to make updating the documentation a step if your story workflow.) This obviously adds overhead onto development, but it will definitely save you time down the road, both in recalling how screens work, and potentially training new team members.

In a cross-functional environment, when the same product is being built on multiple platforms, the team with the best documentation (or in many cases, the team with any documentation) becomes the authority on how the product works. Knowing your product is the single best thing you can do not only for the benefit of the product itself, but for the benefit of your dev team, and of other dev teams building the same thing.