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.
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.
Lexware LexOffice in the test
Lexware Financial Office 2015 put to the test
Intrexx 7 in the test
- Why are table knives boring
- What ENTPs love in relationships
- How is Apple AirPods Pro
- What scares people about eating hot dogs?
- A PharmD student can do research
- What is the Best Bowflex Home Gym
- YouTube is banned in Saudi Arabia
- What is hot spotting in Hbase
- Waste money on pre-workout
- Are there fleas in Phoenix AZ
- What do hammer and pimple symbolize
- Were Brahmins against Lord Buddha
- What is a checkpoint on Instagram
- Men like to fight
- What simulations are used in evolution
- What are the ways to restore memory
- What is observation in the scientific method
- Is Anlasana the best Turkish romantic song
- What is the GPL license for Linux
- What are the downsides when you doubt yourself
- North Korea has a president
- Is there a war against white men?
- Have you written answers on Quora
- Where do young Caucasians live in Jakarta