How Can a Good App Documentation Help You When Working with a Software House?

In this article, I will share a few tips enabling you to prepare specifications that will facilitate valuation for any good software house, and thus let you avoid misunderstandings.

Application description is clear for you and very simple to implement for all others who read it as long as you...

…know the methodology you want to work to. You may immediately wonder if it that means that you have to learn about software development methodology.

Let me make it easy for you. The methodology that actually works and is the one you should use in your startup is Scrum. Scrum is flexible, which means that, in the course of production, users testing your assumptions will share very valuable suggestions, allowing you to implement them within a few weeks.

I know the name of the methodology, does it mean I have to become the expert?

Not at all! The role of the leader is to set the course of development, but also organize and control the company. You just need basic knowledge of Scrum to effectively control what happens to your application, i.e.

  • What are Backlogs and User stories?
  • What are sprints and retrospectives?
  • Who is the product owner, scrum master, scrum team and what do they do?

That's basically it. This knowledge will help you have a picture of how your team, or in this case, a software house works, what you can expect and how to control the course of work. More can be found on official Scrum website,

How to make specification and user stories to let you avoid the "but I thought that...” disease

What should it look like? Simple, e.g.:

  • Actors in the application:

    • System administrator
    • Application user
  • User stories:

    • As an application user, I can log in to the system
    • As an application user, I can edit my profile
    • ….

Isn't that simple? Please note that the "user stories" about the content: “As an application user I can edit my profile" give you the opportunity to ambiguous interpretation which translates into... trouble.

User stories:

  • As an application user, I can log in to the system

    • Giving e-mail address as a login
    • With a password that is at least 8 characters long.
  • As an application user, I can edit my profile

    • I can add my profile photo
    • I can crop the thumbnail
    • I can change my password
    • I can edit my address
    • I can edit... etc.

Only such analysis will allow you to painlessly go through the control of the application submitted by the software house. Try to stick to the so-called acceptance criteria, i.e. a detailed description of user activities.

Such specification is to be written in simple language and be easy to understand for everyone.

When you send the software house so written assumptions for valuation assumptions, request an Excel sheet, stipulating how many hours particular functionalities will be assigned. In this way you can easily control your budget, scope of work and credibility of the partner.

If the pricing you receive lacks a detailed cost breakdown, do not agree to work with the contractor, this will save you from the dreaded "but I thought that..." disease - Yeah, right.

How detailed should the specifications be?

The level of specification detail should be such that allows developers delivering valuation of any functionality within 8h. If you overlooked anything, the software house should get back to you with further questions. However, if you your user stories are too general, the software house may polish the document for you at an extra cost. How much is this extra? Preparation of user stories for a startup takes roughly 16 to 40 hrs of work.

Remember: A common mistake when creating such specification is that initially it may seem that the application should contain a lot of functionality and leaders begin to strive for perfection, rather that result. Perfection comes over time while the result can quickly be verified and amended.

Example: A taxi booking application.
The primary functionality of the application will allow to order a taxi to the specified address and time. Additional functionalities like card payment or a request for English-speaking drivers only may be added later.

To properly determine the shape of MVP, you must do the work associated with the Business Model Canvas. The version of the MVP application and Business Model Canvas is extremely extensive subject and deserves another article itself.

If you have questions, please comment below or contact me directly.


Krzysztof Marszałek

I am the CEO of - a software house specializing in building usable web and mobile apps for STARTUPS.