Home

Welcome to the IPT Survey automation tool documentation!

This project automates the complete workflow of conducting student surveys about university teachers. Instead of performing each step manually - from collecting information about teachers to publishing the final results - the toolkit provides a set of utilities that streamline the entire process.

Key Features

• Distributed data collection – each study group provides only the information relevant to them using simple JSON files.
• Automatic Google Forms generation – survey forms are created from predefined templates with minimal manual work.
• Automated response retrieval – responses are downloaded directly from Google Forms and converted into Pandas DataFrames for further processing.
• Result visualization – numerical survey results are transformed into clear, informative charts.
• Telegram integration – generated visualizations are automatically published to a Telegram channel, while answers to open-ended questions are posted as comments.

Requirements

This project requires Python and Docker.

• Python is used for all scripts in the survey pipeline, including information processing, Google Forms generation, response collection, analysis and visualization.
• Docker is used only for running the Telegram posting bot, which is responsible for publishing survey results and comments to a Telegram channel in a consistent runtime environment.

To get started, first clone the repository:

git clone https://github.com/ShkalikovOleh/ipt_survey.git
cd ipt_survey

For Python dependency management, this repository uses uv as the recommended package manager. It is fast, reproducible, and simplifies environment setup. To install uv, follow the official installation instructions

To install all dependencies and synchronize the environment, run:

uv sync --locked

Workflow

The survey workflow consists of four main stages:

1. Information collection – gathering structured information about study groups, teachers, and courses.
2. Forms generation and distribution – automatic creation of Google Forms from a template and making them available to students.
3. Results collection and processing – downloading responses, transforming them into structured datasets, postprocessing and generating visualizations.
4. Results posting – publishing the results to a Telegram channel, including open-text responses in the comments.

Each stage is described in detail in the corresponding section of this wiki.

By following these guides, you can conduct a complete teacher survey with minimal manual intervention while keeping the process consistent, reproducible and easy to maintain.

Team Roles and Collaboration

Although the entire survey pipeline can technically be managed by a single person, the project is designed to support collaboration and is significantly more effective when responsibilities are shared.

The following tasks benefit from having multiple contributors:

• Information collection (steps 1 and 2) – each study group should provide information only about their own courses and teachers. This distributed approach reduces the workload for individuals, improves accuracy, and makes it easier to keep the collected data up to date.
• Survey distribution – once the Google Forms have been generated, they should be shared with students through the communication channels used by each study group. Having representatives from multiple groups ensures that every group receives the correct survey link.
• Student engagement – encouraging students to complete the survey is just as important as distributing the forms. Group representatives can remind their groupmates about the survey, answer basic questions, etc which can help achieve a higher response rate.

The remaining parts of the workflow can be performed by a single coordinator:

• generating and publishing Google Forms,
• collecting and processing responses,
• generating visualizations,
• publishing the results to the Telegram channel.

In practice, a typical survey campaign involves one coordinator responsible for the technical workflow and several study group representatives who collect information, distribute survey links, and encourage participation within their groups.

Questions, Issues, and Contributions

If you encounter a bug, have a question about the survey workflow or believe the documentation can be improved, please open an issue in this repository.

If you would like to fix a bug, improve the code, or extend the functionality, feel free to open a pull request. If your changes are substantial or you plan to maintain your own version of the project, you are also welcome to fork the repository.

This project is distributed under the GNU General Public License v3.0 (GPL-3.0). The license allows you to use, modify, and redistribute the software, provided that derivative works are also distributed under the GPL-3.0 license and the corresponding source code is made available.