http://www.phparch.com \ November 2018 \ 17How to Knock Down Any Project in Ten StepsREADME files are a good example.
Often they will be in the main reposi-
tory of the project and are supposed
to explain to a new person how to run
the project quickly on their machine.
The easiest way to verify the clarity
and objectivity of this type of docu-
mentation is for it to be reviewed by
an outsider. At the same time, the
README file is a good starting point
for writing documentation if we don’t
have it yet.
Recently, Ola Sendecka from Buzz-
feed went through this process^2. She
made some important points that I’ll
paraphrase here. First, we have to
answer four questions before writing
documentation:
- what do we want to document,
2. how do we want to document,
3. who will be responsible for the
documentation, and
4. and how do we make it easier to
find documentation?
The structure of an example
README file proposed by Sendecka
may look like this: - Name of the project,
2. List of persons responsible for proj-
ect maintenance,
3. Examples of usage (code snippets),
4. Running the project,
5. Project dependencies, related
services, technologies used,
6. Runbook (routine procedures and
operations),
7. References to logs, monitoring,
dashboards, and
8. Links to complete project docu-
mentation.
The above skeleton is a very good
beginning for the documenta-
tion. When we come to the point
where we want to describe more, for
example, processes, algorithms or
information flow or connections with
other micro-services, then there will be
time to write fully-fledged documenta-
tion. I encourage you to read this article
2 went through this process:
https://phpa.me/buzzfeed-better-docsto learn about different ways of dealing
with documentation.- Re-Inventing the Wheel
In programming the hard part isn’t
solving problems, but deciding what
problems to solve.- Paul Graham
There are teams and companies that
do not recognize ready-made solutions
even to the slightest degree. Sometimes
it’s because the main programmer
thinks they’ll write a better framework
after hours.
An example: an architect pushes the
theory that all tools used by program-
mers should be created within the
company. Using a custom framework
is probably becoming rarer, but it
still happens for a lot of legacy code-
bases, and that’s not surprising. What
surprised me was the fact that the
company created its own libraries to
handle database connections, HTTP
requests, authorization, encryption,
etc. Why? Unfortunately, I don’t know
the answer to this question, but I know
what the consequences of such an
approach may be.
The effect is that libraries are created
which implement the same ideas as the
existing open source software (OSS),
but with a more limited scope, few or
no tests, and almost no documentation.
There are fewer developers to develop
such a tool than in the case of OSS.
Sooner or later code rots, programmers
leave the company, and it turns out that
a lot of time has been wasted while it
could have been used on much more
important topics. Like actually writing
business logic code.
In the life of every developer, there
is a time when they have to write their
own framework, ORM, and CMS.
Every developer likes to try their hand
at a new language, using a new library,
or framework. This is a very valuable
experience, and I think everyone
should go through it with one excep-
tion: it should not happen at work. Inmost cases, ready-made solutions are
enough, and your case is probably not
unique enough to require you to write
an ORM from scratch.- Silos and Rockstars
One bad programmer can easily
create two new jobs a year. Hiring
more bad programmers will just
increase our perceived need for
them.- David Parnas
As programmers, we like to work in
silence and peace. When nobody asks
us questions, doesn’t say anything,
doesn’t take us to meetings, we work
best. Sometimes it can lead to extremes
and work is performed in a so-called
silo. This happens when the team gets
a task and then cuts itself off from the
rest of their coworkers, often for an
extended period. The problem with this
approach is that there is no feedback
loop. Without frequent feedback, it is
difficult to verify if the work is going
in the desired direction. This, in turn,
creates the risk that a lot of time will
be devoted to work that turns out to
be incomplete, inconsistent with stake-
holder assumptions, or unnecessary.
Sometimes we are also dealing with
so-called knowledge silos. These are
the so-called “ninja developers” or
“programming stars.” On the one hand,
these are funny job descriptions that
can be found in job advertisements. On
the other hand, it is very often a person
who is perceived as the most important
of all developers. Such people have a lot
of knowledge, but they do not share it.
In this way, they become a bottleneck in
decision making and hold whole teams
hostage.
Example: only one person at a
company knows a certain system or
process and defends that knowledge
like a lion. Without delegating tasks,
without automation, or writing docu-
mentation, they become irreplaceable.
Real drama occurs when such a person
decides to leave the company.