Documentation - Bringing sustainable projects to life

For every completed project, the customer receives complete, understandable, and permanently usable project documentation. This explains how the developed solution works, how it is applied, and which technical components interact in the background.

This includes, among other things, the most important functions, how to use the application, the data sources used, processing flows, interfaces, technical dependencies, and information on operation, updates, and further development. Known limitations and project-specific features are also clearly documented.

This ensures that even after handover, it remains clear how the solution is structured, how it is used correctly, and what needs to be considered during later adaptation or further development.

The documentation will be provided in two coordinated formats:

1. as a standalone HTML document for visual use in the browser (local website in the browser),

2. as a structured Markdown document for use in a project-related chatbot or other AI-supported knowledge system.

Both formats are based on the same shared project information. This provides the customer with clear visual documentation and, at the same time, a compact, machine-readable knowledge base.

Here's an example: https://heiselanalytics.github.io/DocumentationExample

Initial situation

During the implementation of a technical project, a large amount of relevant information is generated. This includes operating instructions, functional descriptions, data sources, interfaces, technical processes, dependencies, and project-specific settings.

This information is often scattered across various files, emails, meeting notes, or the source code. As a result, once the project is completed, there is often no central location where the functionality of the solution is fully and clearly described.

This makes subsequent use, handover, or further development particularly difficult. New employees or people not directly involved in the project must first familiarize themselves with different sources. Technical changes sometimes require existing relationships to be re-analyzed.

Even traditional documentation isn't always permanently usable. It often consists of multiple files, externally embedded images, or links to websites and storage locations. If files are moved, folder structures are changed, or websites are shut down, individual parts of the documentation may no longer display correctly.

Additionally, many documentation formats are not ideally suited for use by a chatbot or AI system. Complex formatting, extensive layout information, and unnecessary repetitions make processing more difficult and increase token consumption.

Therefore, technical project documentation is needed that can be easily opened, shared, and archived. At the same time, it should be structured in such a way that the information it contains can be efficiently used by a project-related chatbot.

Defined solution

The documentation is individually tailored to the developed solution. It describes the application from the users' perspective and simultaneously documents the technical aspects required for operation, customization, and further development.

Depending on the project, it may include:

• the structure and operation of the developed solution,

• the description of the most important functions,

• typical usage steps and use cases,

• data sources and inputs used,

• the processing and merging of data,

• Interfaces to other systems,

• automated workflows and update processes,

• technical requirements and dependencies,

• relevant settings and configurations,

• known limitations and error patterns

• Instructions for operation, maintenance and further development.

Two different documentation formats are created from this content.

The first result is a standalone HTML document. This contains the complete visual project documentation, including navigation, text, tables, images, code examples, and project information.

All content required for display is directly embedded in the HTML file. Therefore, the documentation does not require an additional folder structure, external image storage, or a publicly accessible website.

The customer simply needs to open the HTML file. The documentation will then be displayed directly in a modern browser. No installation or special documentation software is required.

The documentation is provided as a locally stored file. Unlike a publicly accessible website, it is not automatically accessible via the internet. From a security perspective, it can be compared to a Word or PDF file: as long as the customer does not share, upload, or store the file in a shared repository, other people will not have access to it.

The file can be saved locally, archived, sent via email, or selectively shared via an internal file repository. The customer thus decides who has access to the documentation. Because all content is contained in a single file, text, images, navigation, and design remain completely intact even when shared.

The same applies to the additional Markdown file provided for the chatbot. It, too, is initially a locally stored file and not publicly accessible. Only when the customer explicitly integrates it into a chatbot, an AI system, or a shared repository does it become accessible to authorized individuals or systems. The customer thus retains control over where the documentation files are stored and who can access them.

The second result is a structured Markdown document . This contains the same shared information in a clear and text-oriented format.

The Markdown file is intentionally structured to be simple and clear. Unnecessary formatting and technical layout information are avoided. This makes the file easily readable for humans and efficiently processed by AI systems.

It can be used as a knowledge base for a project-related chatbot.

This allows users to ask questions about the developed solution, for example:

• How is a specific function used?

• Which data sources are processed?

• How frequently is the data updated?

• What does a particular output or error message mean?

• Which interfaces are used?

• What are the requirements for operation?

• What needs to be considered when adapting or further developing a product or service?

The chatbot does not replace the documentation. It offers additional and particularly easy access to the information it contains. It can connect content from different sections and explain relationships without the user having to search for the relevant chapter themselves.

A dedicated internal tool was developed for the consistent creation of HTML and Markdown documentation. This tool combines the individual documentation elements and generates the two output formats from them.

Result and added value

The customer receives complete visual project documentation in a single HTML document. Here's an example: https://heiselanalytics.github.io/DocumentationExample

The documentation can be opened directly in the browser and is not dependent on a running website, a hosting provider, or a specific storage location. An internet connection is also generally not required to open the documentation.

This allows the file to be stored long-term and reused at any time. It can be shared with employees, external partners, or future project managers without any additional preparation.

The customer particularly benefits from the fact that:

• the documentation can be opened in the browser with one click,

• no additional software is required

• all content is contained in a single file,

• Images and tables do not need to be supplied separately.

• no external links or image paths can be damaged,

• the file can be easily sent and shared,

• a complete state of the solution can be archived long-term,

• new people can familiarize themselves with the project more quickly,

• Operation and further development should not depend solely on the original developer.

The documentation supports both daily use and technical handover. Users will find explanations of functions and operation, while those responsible for technical aspects will receive information on data sources, processes, interfaces, and dependencies.

The additional Markdown file provides the customer with a compact and particularly readable knowledge base for a project-related chatbot.

Thanks to its clear structure and simplified formatting, the document can be efficiently processed by an AI system. Token consumption remains low compared to extensive websites, PDF files, or unstructured document collections.

This enables direct and dialogue-oriented access to existing project knowledge. Users can ask specific questions and receive answers based on the documented content.

The chatbot can also combine information from multiple sections. This allows not only for querying individual facts, but also for explaining relationships between functions, data sources, technical processes, and potential limitations.

The combined approach thus offers two different ways to access the same information:

• The HTML document serves as complete and visually prepared project documentation.

• The Markdown document serves as a compact knowledge base for chatbots, search, and AI-powered information systems.

This means the documentation is not just a final document. It remains an actively usable component of the developed solution and supports its use, operation, and further development beyond the original project handover.

The documentation also includes a central section for support and contact information. The contact details displayed there are automatically updated whenever an internet connection is available. This ensures that the customer has access to valid contact options even if phone numbers, email addresses, or other information changes after the initial project handover.

If the current query cannot be performed, you will be redirected to the Heisel Analytics contact page. The most up-to-date general contact information is available there.

In addition, the customer receives a separate emergency number for their project. This is intended for particularly urgent or business-critical cases and allows for prioritized contact. This provides a direct contact option, alongside the regular support channels, for situations requiring timely action.

The emergency number is provided on a project-specific basis and separately from publicly accessible contact information. It is intended exclusively for authorized contact persons of the respective project.

Technical design

The HTML documentation is provided as a separate file and can be opened in current browsers.

All necessary documentation content, images, and design elements are directly embedded in the file. No additional folder structure or publicly accessible documentation server is required for display.

This allows the file to be saved and distributed independently of the original project directory. As long as a modern browser is available, the documentation can be opened locally and displayed in its entirety.

The Markdown version is provided as a clearly structured .md document. It avoids unnecessarily complex formatting and is designed so that individual content elements are clearly organized, easily updated, and efficiently processed by a chatbot.

Both documentation formats contain key project information such as:

• Project name,

• Documentation version,

• Date of creation,

• Date of last modification.

This allows the documentation to be clearly assigned to the respective stage of the developed solution.

Since the documentation can be shared, sent and integrated into a chatbot, it does not contain any secrets or security-critical access information.

Secrets and confidential access information will be provided separately and via a suitable, secure transmission channel.

This allows the documentation to be shared within the company or integrated into an AI-supported knowledge system without disclosing passwords, keys, or other security-critical information.