What web products should be created

Document web projects sensibly

Unconsciously and against better judgment, billions of lines of source code are written down every day, which are never documented and explained. Most of the time, the schedules until the launch of the website or the product are so tight that there is no time left for documentation. Missing explanations for the source code can also be part of the business model.

Because anyone who has invested his working time in developing a template for Wordpress & Co. has no increased interest in the customers making adjustments or fundamental changes themselves.

Documentation is a must!

Every software project - and websites, stylesheets or PHP functions are no exception - should have documentation. At a minimum, rudimentary information on why this particular route was chosen to solve a problem or which function a code block takes on exactly saves a lot of time.

Because even if only one person works on the sources, he or she must first think back to the structure of the code before changes can be made safely and in the correct places. And without documentation, changes in the team become pure gamble.

Those who act on behalf of customers are faced with the task of documenting their work for legal reasons. A new website, an extension for a shop or a CMS or just a new look for a website - from the point of view of lawyers, these are simply products that were created or sold on behalf of a customer. And what is just code for developers is an ideal theater of war for lawyers and judges around issues such as warranty, liability and even consumer protection.

In the past few decades, the court opinion has prevailed that "software" always also consists of documentation that must be accessible to the customer. As a rule, however, there is a dispute in individual cases about the form of this documentation and whether it is sufficient.

Use CC licenses correctly

Concrete results and indications of what good documentation should look like can hardly be drawn from countless legal disputes. In contrast to many other areas from the technical descriptions, in the software documentation you will not find any standardized information on how such documentation should look. The DIN standards adopted decades ago have been withdrawn without replacement. So the letters of these outdated descriptions have at most the character of a first handout.

Make exact customer agreements!

Precisely because it is nowhere to look up exactly how extensive documentation should be, it should be regulated before the start of the project how extensive the documentation obligations are to be defined. Standard phrases from forms for contracts for work and services leave too much potential for conflict, since it is usually only regulated that the contractor also documents his work.

It is advisable to find precise formulations here as to the form in which documents can be documented. The more precisely you regulate what the client expects from you, the better. Most web workers should have made the experience over the years that the desire of the contact person for comprehensive documentation increases to the same extent as the investment volume in the project. So it is best to determine how your activity report should look like and how the actual programming is to be documented before placing the order. Does the customer expect a printed and detailed list of functions, classes or structures?

User Guide - a different take on the same thing

However, the documentation in the sense of a documentation requirement for software creation does not necessarily also include a manual for the users, i.e. the actual users of the system. The documentation rather describes the structure of the product and makes its creation appear comprehensible.

A service provider who is given the task of revising the source code (or, more generally, the product) is thus able to complete the task more quickly and, above all, is prevented from making a mistake that may lead to: that the whole system no longer works. On the part of the client, however, there is always the opinion that the user manual belongs to a documentation. One thing is clear: Anyone who develops a plug-in for a CMS or shop system and addresses the end user should deliver the product with a manual.

For the sake of sales alone. And of course, a user book of standard software that is sold to end customers has a different legal status than adjustments to a shopping cart system that were developed on behalf of another company.

If the client also wants instructions for the users of the system, you should also get paid for the production of this additional guide. Because once you have documented your work, the specific instructions are an additional service for the end user. The client could, for example, create these documents himself.

Not enough - simple comments

The easiest and fastest way to document the source code is to make frequent use of the comment function provided in all scripting and programming languages. This is quick and easy and structures the content of the source code.

The greatest advantages of this approach are obvious. If you write comments directly into the source code during development, you hardly lose any time with documentation. In practice, however, the comments are only suitable to a limited extent. On the one hand, it is hardly possible to get a complete overview of the project. While working together in a team, comments can be used sensibly to point out areas that require revision.

Inline comments are only suitable as an exclusive document for documenting and structuring theme and template files for Wordpress or similar systems. When writing, you should also remember that the documentation should be able to explain the connections in the project to a colleague or new employee at any time. For example, you can use comments in the source code to indicate that a variable will be defined on the next lines. But describing the connection with other variables becomes just as difficult as you have to do without graphical definitions.

Popular and common: Doxygen

When it comes to documentation, there are different perspectives and approaches. The developers want to complete the documentation in the shortest possible time and with little effort. The customers, on the other hand, value a description that is as detailed as possible, which should not raise any questions.

Reviewing the documentation should also take as little time as possible, so the reader can find his way around the source text and the explanations as quickly as possible. Doxygen has been in development for a long time. With the application, you write the explanations that will later make up the documentation directly in the source text. When creating the description, the software works in a similar way to a compiler during development. The source text is transferred to the program.

Documentation tools

In addition, some other text documents containing important parameters are evaluated. This includes specifications for headings, headers or footers, any graphics to be used and the description of the layout. From all this information, Doxygen can create documents in a number of different target formats. XML files, documents in LaTeX and RTF files are supported. Explanations can then also be imported into familiar word processors using this format. Doxygen directly supports the source code formats C, C ++, C #, IDL, Java, PHP and Python. By making additions to the control files, it is also possible to adapt to other programming languages.

A number of other applications that are suitable for different programming languages ​​and support different output formats work according to the same principle.

Quickly to the user manual

The documentation of source texts of all kinds is more a domain of more or less detailed texts. Standardized diagrams (e.g. UML) help professional users to understand the relationships. The users of an extension, a website or a program, on the other hand, are interested in being able to work with it as quickly as possible.

This is where images can play out their full power, provided that the surface of the product does not change permanently. Screencasts (filmed processes on the screen) are, if they have been provided with sound or visual explanations, a very good opportunity to introduce users to the first steps in a new environment.

Business intelligence as a matter for the boss

But if it comes down to a targeted lookup, nothing beats a linearly structured, written documentation, regardless of whether offline or online. What it has in common with the description of the source code is that the least possible effort should be made to produce it. Developers can use various tools to solve this task.

ScreenSteps: this is the name of a platform on which a team can jointly create user manuals and documentation. The basis for this is software that is offered for both Windows and Mac. The program takes screenshots at regular intervals or completely manually.

The recordings are then simply provided with prefabricated symbols or labels that indicate special areas. Each screenshot becomes a single page in the documentation (at least according to the default settings). Texts are then also stored on these. You can test the tool in a free trial phase. After that, monthly fees are due. Anyone who works exclusively on a documentary alone has to reckon with 129 US dollars per year for this.

Dr. Explain: Dr. Explain, which is priced in the same league, but is exclusively reserved for the Windows world. It knows a number of other output formats, such as the Windows typical CHM format of the help files, but has to forego the possibility of online collaboration. A demo version is also available for this product.

Thanks to numerous applications, the topic of software documentation has lost much of its horror. However, the programs for the description of the sources expect the users to work on the compilation of the work environment and familiarization with the syntax. This also applies analogously to the tools with which the user documents can be generated. Thanks to the graphical user interface, there is little effort to familiarize yourself with these tools. In most cases, regardless of this, hardly all of the options contained in the applications are exhausted.

Invoices and bookkeeping

Lexware LexOffice in the test

LexOffice is a cloud service that is specially tailored to beginners and lone fighters. We are testing the service.
Commercial complete package

Lexware Financial Office 2015 put to the test

We have Lexware Financial Office 2015 in the test: In the core business, the commercial software convinces with well thought-out processes.
Convenient implementation of company portals

Intrexx 7 in the test

Integration platform, knowledge portal, mobile development environment - Intrexx 7 has many faces. We have Intrexx 7 in the test.