README – how to

README files have a long tradition in software projects. These originally plain text files contained license information and instructions on how to compile the corresponding artifact from the source code or important notes on installing the program. There is no real standard how to build such a README file.

Since GitHub (acquired by Microsoft in 2018) started its triumphant march as a free code hosting platform for open source projects, there was quite early the function that the README file as the start page of the repository display. All that is required is to create a simple text file called README.md in the root directory of the repository.

In order to be able to structure the README files more clearly a possibility for a simple formatting was looked for. Quickly the markdown notation was chosen, because it is easy to use and can be rendered quite performant. Thus, the overview pages are easier to read for people and can be used as project documentation.

It is possible to link several such markdown files together as project documentation. So you get a kind of mini WIKI that is included in the project and also versioned via Git.

The whole thing became so successful that self-hosting solutions such as GitLab or the commercial BitBucket have also adopted this function.

Now, however, the question arises as to what content is best written in such a README file so that it also represents real added value for outsiders. The following points have become established over the course of time:

  • Short description of the project
  • Conditions under which the source code may be used (license)
  • How to use the project (e.g. instructions for compiling or how to include the library in own projects)
  • Who are the authors of the project and how to contact them
  • What to do if you want to support the project

Meanwhile, so-called badges (stickers) are very popular. These often reference external services such as the free Continuous Integration Server TravisCI. These help to assess the quality of the project.

On GitHub there are also various templates for README files. However, you also have to look a little at the actual circumstances of your own project and judge which information is really relevant for users. But such templates help a lot to find out if you might have missed a point.

The fact that pretty much every manufacturer of source control management server solutions has integrated the function to display the README.md file as the project start page for the code repository means that a README.me is also a useful thing for commercial projects.

Even if the syntax for markdown is easy to learn, it can be more comfortable to use a MARKDOWN editor directly for extensive editing of such files. You should make sure that the preview is displayed correctly and not only a simple syntax highlighting is offered.

Links are only visible for logged in users.

Links are only visible for logged in users.

This is how corporate knowledge becomes tangible

The expertise of its own employees is a significant economic factor for any organization. This makes it all the more important to store experience and expertise permanently and make it available to other employees. A central knowledge management server takes on this task and helps to ensure long-term productivity in the company.

(c) 2011 Marco Schulz, Materna Monitor, Ausgabe 2, S.32-33
Original article translated from Deutsch

The complexity of today’s highly networked working world requires smooth interaction between a wide range of specialists. Knowledge transfer plays an important role here. This exchange is made more difficult when team members work in different locations with different time zones or come from different cultural backgrounds. Companies with worldwide locations are aware of this problem and have developed appropriate strategies for company-wide knowledge management. In order to introduce this successfully, the IT solution to be used should be seen as a methodology instead of focusing on the actual tool. Once those responsible have made the decision in favor of a particular software solution, this should be retained consistently. Frequent system changes reduce the quality of the links between the stored content. Since there is no normalized standard for the representation of knowledge, significant conversion losses can occur when switching to new software solutions.

Various mechanisms for different content

Information can be stored in IT systems in various ways. The individual forms of representation differ in terms of presentation, structuring and use. In order to be able to edit documents geminus conflict-free and version them at the same time, as is necessary for specifications or documentation, wikis [1] are ideally suited, since they were originally developed precisely for this use. The documents stored there are usually project-specific and should also be organized in this way.

Cross-project documents in the wiki are, for example, explanations of technical terms, a central list of abbreviations, or a Who’s Who of company employees including contact data and subject areas. The latter can in turn be linked to the technical term explanation. Comprehensive content can then be kept up-to-date centrally and can be conveniently linked to the corresponding project documents. This procedure avoids unnecessary repetitions and the documents to be read become shorter, but still contain all the necessary information. Johannes Siedersleben already described the risks of excessively long documentation in his book Softwaretechnik [2] in 2003.

Knowledge that has more the character of a FAQ should better be organized via a forum. Grouping by topics in which questions are stored along the lines of “How can I …?” makes it easier to find possible solutions. A particularly attractive feature is the fact that a forum of this kind evolves over time in line with demand. Users can formulate their own questions and post them in the forum. As a rule, qualified answers to newly posed questions are not long in coming.

Suitable candidates for blogs are, for example, general information about the company, status reports or tutorials. These are documents that tend to have an informative character, are not form-bound or are difficult to assign to a specific topic. Short information (tweets [3]) via Twitter, thematically grouped in channels, can also enrich project work. They additionally minimize the e-mails in one’s own mailbox. Examples include reminders about a specific event, a newsflash about new product versions or information about a successfully completed work process. Integrating tweets into project work is relatively new, and suitable software solutions are correspondingly rare.

Of course, the list of possibilities is far from exhausted at this point. However, the examples already provide a good overview of how companies can organize their knowledge. Linking the individual systems to a portal [4], which has an overarching search and user administration, quickly creates a network that is also suitable as a cloud solution.

User-friendliness is a decisive factor for the acceptance of a knowledge platform. Long training periods, unclear structuring, and awkward operation can quickly lead to rejection. Security is also satisfied with access authorization to the individual contents at group level. A good example of this is the enterprise wiki Confluence [5]. It allows different read and write permissions to be assigned to the individual document levels.

Naturally, a developer cannot be expected to describe his work in the right words for posterity after successful implementation. The fact that the quality of the texts in many documentations is not always sufficient has also been recognized by the Merseburg University of Applied Sciences, which offers the course of study Technical Editing [6]. Cross-reading by other project members has therefore proved to be a suitable means of ensuring the quality of the content. To facilitate the writing of texts, it is helpful to provide a small guide – similar to the Coding Convention.

Conclusion

A knowledge database cannot be implemented overnight. It takes time to compile enough information in it. Only through interaction and corrections of incomprehensible passages does the knowledge reach a quality that invites transfer. Every employee should be encouraged to enrich existing texts with new insights, to resolve incomprehensible passages or to add search terms. If the process of knowledge creation and distribution is lived in this way, fewer documents will be orphaned and the information will always be up-to-date.