Documentation at the beginning of a project working alone

Question

Studying object-oriented analysis and design I found various types of documents that are built before any code is developed. Among these documents are user Stories, use cases and several UML diagrams. All this, however, is always discussed in the context of a development team.

One thing that is clear is that these documents exist so that it is possible to have better communication between the team members, that is, the idea is to improve communication. In addition, some documents are extremely formal and exist by company rules in which the project is being developed.

I, however, work alone, and have always been in doubt as to what documents they really are necessary when starting a project. I usually use basically user Stories, use cases and the class diagram, but I’ve heard that even the class diagram could be dispensed with in cases like this.

In that case, when starting a new project working alone, what documents are really indispensable thinking not only at the beginning of the development but at the future of the project?

Answer 1

As this seems to be the focus of the question, I will only talk about the documentation of engineering software and not documentation of use of the software.

Your observation that the documentation aims at communication in the team is correct by accepting the premise that the client (or the customer representative) is part of the team. That is: documentation aims at communication client <-> team <-> team.

There are those who write documentation to even let other teams take over the system in the future and benefit from this documentation.

But writing a lot of documentation trying to secure the future is an increasingly disused practice in our industry. Because after so many decades of writing tons of documentation we’re learning that it never helped much ^[1].

We are trying to bring to software development ^[2][8] the Lean thinking ^[3] that made the Japanese automotive industry a fabulous success and that after that has been helping in several areas of activity around the world ^[4].

According to Lean thinking, it is essential to eliminate all waste. All activity that does not add value to the customer needs to be eliminated. So according to this current, you should only write documents that add value to the customer.

In addition, the second principle of Agile Development ^[5] says:

"We value more software running than comprehensive documentation."

And Agile is becoming the industry standard ^[9] to the detriment of other models that require a lot of documentation.

How to know if a document adds value?

Questions that help identify whether a document has the potential to add healthy value:

To whom this document aims to help?

Someone will read this document?

If you cannot identify the direct beneficiary of the document or have great doubts whether this document will even be read, it is best not to write it; at least not now.

When it’s worth writing a document even if no one will read it later?

Writing helps structure ideas and make discoveries.

So writing class diagrams, sequence diagrams and use cases help deepen the understanding of requirements and figure out how to solve the problem.

But documents to this end should not be seen as system documentation, need not be formal and should not be kept longer than the duration of the task of implementing that particular piece of software (that’s right, throw it in the trash after using).

Documentation of software requirements

You spoke of user Stories - they are excellent for describing requirements. @Luiz Vieira has already made a beautiful description of them in his indispensable answer. What I have to add is that they should be thrown out as soon as the project ends or even sooner as the Feature is delivered. They should not be seen as perennial documentation of the software otherwise they lose their flexibility and simplicity indispensable for success in its use.

In time: a user story can perfectly be accompanied by additional documents. For example, a user story requesting a report may be accompanied by a page simulating an example of a report.

One user story can also be accompanied by your acceptance tests, which describe how the completeness of the history implementation will be verified.

So though user Stories are in fact software requirements, they do not necessarily exempt other documents, which will only be added if there is clear utility.

After all, working alone what documents should I write?

Some documents that add value to both teams and solo projects are:

• Project vision: ^[6][7] what problem will be solved and how it will be solved and what value this solution will be to the customer. This is very important to stay focused and not be distracted by what is not a priority or divert the project from its primary objective. This document is very short and the simple act of writing it, as I said, helps to deepen the understanding of the problem and the solution.

• User Stories: ^[10] As they are written, they help to understand each piece of the problem and the desired solution. After writing, they help prioritize resources to be implemented.

In an agile project, solo or in a team, these are the longest-lived formal documents. The first being the only one born quite complete already at the beginning of the project. User Stories will be written throughout the project. Other documents will be used to help develop the ideas but are very informal and will be dispensed quickly.

Other documents should only be written by specific project demand. If the customer makes a point of paying not only for working software but also for class diagrams and use cases, of course you will have to. In this case, preferably hire a trainee to do them - a good part of it can even be generated automatically by various tools available around ^[11].

Answer 2

The object-oriented analysis and design you are studying is just one of the subjects (perhaps the most popular, say) within the discipline of Software Engineering. Like any other engineering, the goal of the discipline is to assist in the construction of something. However, in this case they are not bridges or electrical circuits, but software systems.

I start with this "reminder" because sometimes we forget that even if we are building something intangible as software, we still use an engineering process that involves observation, measurement, planning and construction. Similarly, a civil or mechanical engineer, for example, uses Blueprints (among other tools) to not only communicate project decisions to co-workers, but mainly to formalize their own project decisions. After all, human memory has its limitations and if you don’t write what you decided today you may not remember the motivation for that tomorrow or next week.

Object orientation is nothing more than a "way of thinking" about how the representation of the problem and the execution of the solution (by the computer) should be carried out. To talk more about it would be complicated here, because the subject would give one or more questions by itself (and, in fact, there is already enough material right here at SOPT that can help you). In any case, many of the documentation tools you cite could be used with any other software engineering approach, such as structured, service-oriented or even agent-oriented design. Why? Because the idea of its use is to assist in the engineering objectives (observe, measure, plan and execute).

In our case (software engineering), to observe means to understand the problem to be solved (the problem may be yours or your client’s), to measure means to estimate the necessary resources (time, money, equipment, modules, and so on), planning means literally choosing the best resolution approach (not only which algorithms, but also what within the problem should or should not be solved, in what ways, using what interactions with users, etc.). And finally, running means programming and mainly testing whether your end product really meets the originally observed need.

Considering these settings, the decision whether or not to use a certain tool or document depends not only on whether you need to communicate decisions to others, but also on your judgment as to whether something is useful or not in that scope design. In the discussions on RUP x Scrum, for example, dogmatism is very common (the XXX approach is bad because it is bureaucratic/simplistic, etc., etc.). But it must be realized, without demagogy, that everything has its usefulness. Of course, too many rules that are blindly followed without purpose only create difficulty, and become that: bureaucracy.

Not to stretch too much, I will close with small discussions about each of the tools you quoted:

• Use Cases. The fundamental part in software engineering is the understanding of the problem to be solved. If a problem is not well understood, it does not matter the quality of the built system because it simply will not serve. That’s why much of the effort in software engineering is put into the so-called requirements analysis. It’s basically about understanding all right what the customer needs. However, software systems are much less tangible products than bridges, cars or chairs. Sometimes customers also don’t know how to describe the details of what they want. That’s why this tool exists. Through it, the engineer builds the scenarios (cases) in which the main functions of the system to be built are used, as a way to pre-validate the understanding that the system will actually do what is necessary (no matter how, at that time). In fact, UML is only a formal language (such as English or musical notation) that assists in communication. As the clients of our projects do not have our technical training, communication with them needs to be as simple as possible. It is no wonder that the use case diagrams are practically childish, that is, they use polka dots, toothpick men and little arrows to communicate this type of information.

• User Stories. The user stories have exactly the same intention of the use cases: help in understanding the problem. But they have the characteristic of describing something the user does or needs as part of their work, primarily the your point of view and in the form of short text sentences. Unlike the use cases, it is not the designer who creates the formal document and asks the user if the understanding is correct, but the opposite. The user describes what he does (tells his story) and transmits it to the designer. This apparent informality (apparent because you still need to store this information for future reference) is what makes this type of tool more attractive to agile methodologies (such as XP). Moreover, the stories do not focus so much (at least initially) on the existence of the system, and therefore allow the engineer to explore together with the client the real needs in a more free way. Why is that a potential advantage? Because communication is not always easy, users may not know how to explain what they need, and sometimes the motivation for automation even part of them (there are others stakeholders involved). The misunderstanding of the needs and the way the problem is currently dealt with makes it unfortunately common for the implementation of a system to change users' routine so drastically to make a task that was once considered reasonably easy on something difficult and even unreasonable. And if the user is not engaged in the use of a system, hardly the development effort will give the expected result.

"I’m gonna go here and automate your budget manual See little block that you take back and forth, okay? You still the will fill manually, only that computer screen. Much easier and safe! Ah, I told you that before every budget you will need to log in with this 8-digit password, 2 special characters and 3 numbers (which you will be required to change weekly)? Yes, on that single terminal that’s right behind the store, about 100 meters from where you usually stand."

• Class diagram. The two previous tools could be used in any software engineering approach you choose (even in structured design). The Class Diagram, however, is much more related to the object-oriented approach because it literally describes the classes the system will use to solve the problem. Again, UML is only the language that formalizes this description. If you use it, assuming that other people have also learned it because it’s something standardized, it’s easy for you to eventually deliver that document to someone else and they quickly understand what the system encompasses. What the system does is best described by another diagram (the Sequence Diagram), since the Class Diagram does not represent the message exchange that the system uses to execute and solve the problem. The Class Diagram represents in particular the problem area. That is, which elements are part of the planned/built solution. For example, if you have a "Customer" class, it is because you represent the customer within your system and have some strong reason for it. In a way, the construction of this diagram assists the engineer in the development of the solution, because it facilitates him to observe which entities need to be represented, what kind of data they will need to maintain and have an initial view of the behaviors they will provide for solving the problem. You wouldn’t need to build it, but this is good practice because it complements the understanding intended by the previous tools. In fact, well-established teams that use these tools in the proper way even have a good traceability of requirements, that is, knowing which elemental parts of the system (classes, components, code files, etc.) exist to meet which functionalities (requirements) and vice versa. This type of analysis makes it a little easier to manage the impact of changes, priority planning, effort estimation, and so on.

In conclusion, I would say that there is nothing that is really necessary (in the strict sense of the word) for you to start a development yourself. However, it is good practice to use some formalism to describe and document at least the understanding of the problem. As other colleagues have already commented, it is known that the maintenance cost is considerably higher later, and this is especially complicated if you notice only belatedly that you built something that was unnecessary or, worse, that does not meet the needs. Furthermore, even if you are currently working alone, remember that this is not the common situation: in most projects you will be working with other people, clients, artists/graphic wear, etc. If you’re already used to working with established practices in the market, it will certainly make it easier for you to get new designs and integrate with other teams.

Answer 3

I will answer with my example.

I’m working on a project with 150 tables and about 2,000 PHP pages.

We know, in the area of "quality", that the cost of maintenance and corrections can go up to 100 times the cost of "creation". We also know that, even if we spend a lot of time to "think of everything", there will be things that we will modify the "imagine" during the process. So we must have two goals:

1) try to imagine everything. Therefore, UML can be good. At the same time, I prefer to put large sheets of paper on the wall and make drawing to have a global view (low-tech!)

2) admit (it is the hardest! ) that we will have to fix, because we are bad programmers.

To predict the second point, whether it is for a large project:

1) Avoid libraries without demonstration that they will have a long life (take a look at the "wonderful libraries" of the past years.)

2) Define a "policy" of name of folders, documents, files etc... There is no "better" solution but you need to define.

And as in ISO: you can do it the way you want, but you need to write it the way you’re going to do it and then follow it the way it was written.

3) Have documentation, but this depends on the project.

In my case, I have a doc with the tables, in alphabetical order. Each table has a type name TAB_CLIENTE and fields have all table names. For example tcliente_nom.

It is possible to have TAB_CLIENTE.nome as it is possible to have also TAB_VENDEDOR.nome, When you are in front of "name" you do not know whether it is the name of the seller or customer. Has description of each field, use, type of content.

I also have a doc with the functions of my libraries.

All this on paper. I do in Word, with version number. When you have a modification (which happens at least once a day), I do the modification in Word, more instead of after-printing everything (the table doc has 77 pages!), printing the modifications -> adhesive tape -> in the document "paper": ready! When you have many modifications, you need to print everything again.

I started a year ago, I’m doing at the same time this "site" and Android apps (also with this kind of doc).

I think the key point is the following: take a look at the "area" of your screen and the "area" of the table. We must admit that trying to use only the screen is a joke because the space is small. So, you need to print. I got an Epson M105 with a paint tank.

• Taking care of documents is like taking care of children. To take care of 10 needs much more effort than 10 times the effort to take care of a.
• A project and how to run on the beach to go swimming: the beginning we go "slowly" on the dry sand, then we will accelerate too much on the wet sand. But then the further we go into the water, the slower we go. In English they call it "diminishing Return": when I do 50% of the second part, I do only 25% of the total... So don’t hesitate to stop and document a lot. In the first part, it will be a waste of time, but the final gain will be huge.
• Put a lot of comments on your code. I’ve been 10 years project head with teams of up to 50 people. Our discovery was that even with "wonderful" tools, the main point is "comments". To have a code that you can modify without problem after 1 year, you need about 80 lines of comments for 100 lines of code.

If you are interested in "Quality Software", take a look here: http://www.crosstalkonline.org/

There’s really a lot of stuff about quality.

Give your opinion, because in this area, exchanging ideas is very good!