This document is an overview of the project creation process, and it will help you decide whether you are ready to work on your project and make sure you are prepared for it.
Level 0. Before you start
On Hyperskill, projects are complex problems that help users apply the skills they have learned. Each project represents a problem close to a real-life situation: our learners create mini-games, databases, and other engaging applications.
We believe that programming lessons are only practical when they let students face complex coding problems on their own. The learner—even a beginner—gets to write the whole code from the first line to the last starting with a description of how the program is expected to operate.
This process introduces our students to the real-life programmer's workflow: customers do not care how the program works on the inside; they want it to perform exactly as specified. At the same time, the programmer should always be ready to modify the code because customers may want to add extra functionality. Simple- and medium-level projects might not illustrate it well, but it becomes apparent when projects become harder.
Creating a good project is difficult, but don't worry—the project managers will guide you through the whole process. To ensure the project follows Hyperskill's general style, we will suggest some corrections. It is a natural part of project creation, so don’t be disheartened. We will try our best to fit your idea into the general style with as few changes as possible.
Project creation includes many steps: coming up with an idea, the stages, the prerequisites, and the tests. Besides, you and our project managers will discuss the project at each step of its creation. Keeping all this in mind, don't expect to create a project in a couple of nights. Usually, it takes about two months from picking the idea up to releasing the project on the platform. It may seem a tall order, but the project creation process involves many people from the team, so it’s reasonable and considers the work of all people involved. We would also like to note that experienced authors (who have created at least one project) can work on a couple of projects at the same time.
More detailed calculations of your input could look like that:
- 2 - 4 hours: developing a project idea and rendering a draft project file
- 8 - 16 hours: editing stage descriptions
- 8 - 16 hours: writing solution files
- 8 - 16 hours: writing test files
- 2 - 8 hours: fixing the project after testing
There are good reasons to take on this challenging process, though! By working with us, you will take part in teaching programming entertainingly and fascinatingly and make acquiring practical programming skills more accessible. That’s a great goal to work for, and it will surely be appreciated further in your career. Moreover, you will learn and perfect many skills in the process: smart planning, deciding what language features to use, implementing good automatic tests, and much more.
Level 1. Idea
First and foremost: choose an idea, i.e., the final product, a program. In the Epic Guide’s section Developing an idea, you will learn more about the criteria for picking cool ideas. The project’s idea should be challenging for users but also interesting and provide good practice. Don’t worry: your project manager or expert have this experience and will help you refine the idea!
When you are ready with the initial idea, write a short abstract in English. Separate it into two short sections:
About: here, you can tell us what’s unique about your project and why somebody should choose to write this type of program.
Result: in this section, you briefly describe what users can learn while completing the project.
Project: SMART CALCULATOR
About: Calculators are a great help: everyone is familiar with them. Why not write one yourself, and make it outstanding? In this project, you will write a calculator that not only adds, subtracts, and multiplies; but is smart enough to remember your previous calculations.
Result: Apart from writing quite a useful program (everyone uses calculators!), you will learn a lot about arrays, stacks, strings, and queues. You will also get a closer experience with the BigInteger class.
Checkpoint here! Show the Hyperskill team what you’ve got. If everything's okay, go to the next level. If not, try to reread the previous text carefully and follow the recommendations of the team.
Level 2. Plan
You can compare projects on Hyperskill with Pokemons: they are evolving from something cute and simple to something impressive. We call the steps of evolution stages.
At this moment, you need to divide your project into such stages. To complete each stage, a student will read some theoretical topics, then develop a stage, and repeat this process until the end. Usually, a project has 3–8 stages. Make a short plan of the stages; give each stage a name, and try to explain what the program will do at the end of each stage.
Let’s continue. Every stage must have a list of prerequisites! Prerequisites are a set of topics the student needs to complete before starting with the next project stage. More information on how to add prerequisites is in the corresponding section of the Epic Guide: Project Prerequisites. If your project idea requires extra information (for example, the knowledge of ANSI encoding), bear it in mind. You will need to explain this part in the stage description later.
Checkpoint again! Show the Hyperskill team what you’ve got. If everything's okay, go to the next level. If not, try to read the previous text carefully again and follow the team's recommendations.
Level 3. Reference solution
At this point, your task is to implement the reference solution as if you were the user solving the project according to the plan. Implement a separate solution for each stage; every solution has to produce the same output as will be required from the user. It will be handy when writing stage descriptions and implementing automatic tests at the following levels.
Level 4. Stage Description
The most fascinating part starts right here! Now you are going to create a description for every stage.
The main goal of the stage is to make the student think about how they can use the prerequisites to develop the code. The description provides extra information required to complete the stage and comprehensively describes how the final product of the stage behaves. You tell the student how the stage will look from the outside, not from the inside.
The description of each stage is a lesson created on the Stepik platform. Each stage represents a separate text step in that same lesson. You can find information on how to do it in a special section of the Epic Guide.
Here is the general structure of a stage description:
- (Optional) Theory: Provide the additional information not covered in the prerequisites;
- Description: Provide a short introduction as to why students must pass this stage;
- Objectives: State the main idea and explain the properties of the final program;
- Examples: Show some instances of input/output.
How to write a proper text? Imagine that you have a 14-year-old friend who read all the prerequisites. Now that friend is asking about the thing you are going to write. Write the description, bearing in mind that this friend will probably read it too. Use Grammarly to correct mistakes!
Read the Number Base Converter project description; it’s another interesting example! The project is available on Hyperskill.
Another checkpoint! Show the Hyperskill team what you’ve got. If everything's okay, go to the next level.
Level 5. Tests
The project description is now done, and so are the stages. Now, it’s time to finalize the process and write automatic tests. Let’s discuss the technical features and then continue with ideas & recommendations.
Many things are already covered in our testing library. Please read the documentation carefully, familiarize yourself with the tests of the example project that your manager will send you, and then start implementing the tests for your project relying on the logic and methods you've just seen.
In a nutshell, our test framework relies on the black box testing approach. It means the test program doesn't care how the solution was implemented (it never “sees” the user’s code). The only things it can do are:
- optionally feeding some input into the user’s program;
- and then check the program’s output (which may include generated files, for example).
One of the main features is that our tests are constructed to provide users with meaningful, not-programmer-oriented feedback in case of a wrong solution. A student trying to solve the stage sees something like this:
Seems that the output is in the wrong format.
Make sure that you use only the following Python structures in the output: string, int, float, list, and dictionary.
Instead of this:
Traceback (most recent call last):
File "/home/molotkova_s/PycharmProjects/Film Quality Predictor/Film Quality Predictor/stage1/solution_1.py", line 44, in <module>
print(data['label'].value_counts() / data.shape)
File "/home/molotkova_s/PycharmProjects/Film Quality Predictor/venv/lib/python3.8/site-packages/pandas/core/indexes/base.py", line 3623, in get_loc
raise KeyError(key) from err
Please, try to foresee what exceptions may arise in the student’s code and handle them with the meaningful feedback, as shown above.
There is another important rule: no overengineering! Keep the tests simple. Maybe in 4 months, we will decide to remove one or two test cases, and it will be easier to do if the code is clean, the variables' names make sense, and so on. We would appreciate it if you group your tests in a file and comment on them. Feel free to copy the code blocks, combine the user outputs required in the stages, and reach out to your manager if you have ideas on optimizing your project's tests.
Alright, that’s it! Now you know about the main stages of creating a project. There’s a lot more to learn, but you will do it in your own pace. Hopefully, this document has made it clearer what lies ahead and has helped you decide if it’s something you’d like to try. Now you are prepared, so good luck with creating your first Hyperskill project!