Blogging as a way of programming it better

There is so much to do regarding all YouTalky that I decided to start blogging about it. Sharing progress in some way to systematise what needs to be done and what I have done already. So many sheets of paper, notes, ideas, flying around.

I think that what always has been my disadvantage was wanting to do things immediately, all of them. At once. Not only this has badly affected my life but also creations. I think that this bad quality was mainly caused by the running world. As a teenager I was able to sit down with Satoshi's designs for hours, doing only one figure and nothing else. Nothing else mattered too. I think because of adulthood, the creation process is not as easy as it was before - at least for a person who has to be responsible for sustaining him/herself. The lack of time pressures and makes me want to finish it now! I forget that this really decreases the outcome - code quality, labels design, incomplete user flow etc.

I believe that blogging about it should change my time perspective and bring back the good way, the beautiful way. The journey.

What is Learning Mode and Highlighting?

Let's start from the easiest one: highlighting.

Just take a Stabilo marker and mark whatever word you don't know. I do that very often when reading a book in a different language. I do that even when I read a book in my own language sometimes. Always using the color matching the book cover.

Ok, so what is learning mode?

Everything that happen afterwards. I open the phone, I open the translator, I write the word, I select the translation, I copy it. Then I open browser, query the translated word and search for meaning and examples. Sometimes I just write the word to the browser directly (if the language I read in is well-mastered by me).

Then sometimes I write down the translation - only if I have a Pigma micron with me. Preferably 0.1 or 0.05 mm. Often times I don't - the highlighted word stay there. The meaning that I have just learned let's me understand the phrase or the idea but then usually it disappears. Sometimes I realise that I highlight the same word multiple times.

All that is the learning mode I do manually, for myself. All those actions increase  knowledge about the language but only mine and only a bit. I would like to:

  • Most of all - understand the ideas in the book quicker and better.
  • Make less effort when translating the words on my phone.
  • Have a higher retention percentage of the words I learn.
  • Share with other people all the effort I made.

Functionality on YouTalky that fills all those requirements (and expands on them) - is what I call The learning mode:

  • Providing list of highlighted words in your paper book, exporting them as flashcards to learn before or after reading for much, much better retention.
  • Ease the process of translating - shorten it to simply typing the word and waiting 1 second to obtain translation, Oxford definition and example phrases.
  • Save the words you translate with one click and learn them later with other people's examples or on your own. This is what consist a base of learning process.
  • Understand a book while reading with your friend (or find a friend if you don't have one).
  • Save for others all the work you do while learning.


My main goal is to:

  • ease my life,
  • enjoy the programming process,
  • increase the value of a particular book copy,
  • learn a language
  • improve the way I understand a book in another language.

I know that the disadvantages may be significant for some people "I don't highlight", "I don't understand other words", "I don't like to read coloured text", "I don't this", "I don't that". Where would we be as humans if we had only executed actions unanimously agreed upon?

"It is not actually increasing the value of the book". It might be true but I have a deep feeling that I need it badly. Thus it has to exist.


The origins of the Idea

I have a couple of books in different languages (Spanish, French, Russian, German) that I did not master to perfection thus sometimes I miss the meaning of words, phrases or entire paragraph (due to more words missing out).

While learning, the retention is low due to the fact that the word will be probably read just once. The writing on the top of highlighted word in a book copy can significantly lower the visuals of the book itself. Most of the times there is no space for writing the meaning of the word and sometimes even the translation itself.

New novel of my favourite writer comes out soon and I should have it in 3 weeks. I know I will struggle with reading it as I will have 5-10 french words on each page to learn. This requires all the mentioned functionality as the book will be beautifully printed (would not like to write on this one, only delicately highlight)

All this, translations, meanings, examples, flashcards, once made and created will be unique for a book copy. Thus the next reader will be able to add on to it (edit) or use it.

How is this helpful

After talking with "some people" I started having doubts regarding the functionality itself. I can't imagine that other people's opinions, can persuade me to drop the things that I deeply care about. Some details should not be discussed as they are part of the creation process. Imagine a painter asking others which colour to use. The core of it is what I need. The base of it is that it should benefit others. How words that I do not know can help others if they are encapsulated in my book copy? They can but the probability of those events - of exchanges with actually people that also learn the particular language - is very low. Maybe it's different for the books in English (that's why bilateral translations have to be available).

All that changes if there is other person reading the same book in other part of the country and translating on her own. This way we could bind those two translations and make them shared. This is creating a unique, new group of words that are newly put together and help only the people who own the physical book copies.

Let's do it - DDD

DDD means Documentation Driven Development. I think it could be applied to non-coding development (e.g. developing a furniture or developing a family trip plan) but let's stick to why it's beautiful in coding world and why I'm applying it and why I can.

To actually write about all this (and make this blog more accessible) I need to focus only on two first points:

  • Write documentation
  • Get feedback on documentation

The idea of this post is included in the first point or even in the point zero (write down the complete idea to follow with the documentation).  I am doing it myself which can be a bit harder - the functionality will be developed purely from idea that comes from my needs and is later refined by my thinking process. I have limited access to the feedback because the user base does not exist yet thus I can test the idea within the closest circle of friends and within my head. To fuel it in moment of no-motivation I am using the joy. Joy of creating and later using something that makes sense in my head. Why start the creating from writing down?

Writing the documentation

Writing is a creative process that draws informations from the brain, from unconscious parts of it. Thus it is necessary to realise about thoughts and facts that are just not immediately visible (or stated in the requirements due to lack of user base). I have started writing this post already after going through the process a couple of times in other medium - mainly Trello card where I developed it.

The description of the functionality when I started writing it down looked like this:

I want to translate words and benefit from translations of other book copy owners.

Does not look like something you should give to a developer if you find one. I am the developer. Thus I do not want to receive a functionality description in this way. Proper development ticket should have good requirements in good user stories so lets work on those.

Getting the feedback

Is very important, because feedback is an information. Information coming to our brain makes it blow in different colours on MRI. Those atomic explosions sometimes can lead to new elements - ideas. Feedback means also self-critique which is looking at the idea from a different perspective, after a while, with a different experience. This is the most useful feedback in my case thus writing down all I experience should be the way I will do things from now on in order to make them well. Naturally it will be prone to a higher errors due to small sample size (or non existing even) but that's the way it is.

Let's do it - Design

There are two ways I know to rapidly design, put the idea in some functional, working, world-reality valid frames.

  • Writing
  • Sketching

I started with the first one as the second one wastes too much paper if the idea is just a concept. It looked like this:

  1. As a BOOK OWNER I want to be able to scan the code on the books cover and access the translation functionality.
  2. The translation functionality consists of active input and passive receiving of words highlighted in the book copy.
  3. Input consists of writing down the word, translation, meaning and adding it to the bag of words later.
  4. Passive receiving consists of list of words and pages where I can see the already available meanings.

I wrote those 4 points and described them. Then consulted friends, went to read. While I was highlighting and just living more ideas came.

  • What if word repeats?
  • What if other people will find new words?
  • What if they will highlight the same copies in different places?
  • What if I want to say that something has been translated badly?
  • What if...

And things kept coming. I began to see the picture in my head so I started sketching.

Sketching begins

Initial versions and ideas for learning mode.

On the top right there is version 1. Initially I thought what would be the best way to show words on multiple pages. Of course before sketching I just had in my imaginative vision only widely used ways: accordion, pagination, table etc.

After sketching it down I got a brilliant idea: what about actually making slider-like pagination on the bottom in a shape of actual pages of the book? Books that have been published in a beautiful way have rounded corners so I will use that.

Then after initial sketches where I started thinking about backend models for the API and data (I am not an expert in that) I made another sketch.

Second iteration and ideas for learning mode.

What if words will repeat? Let's add them only time then. What if other user finds it on another page? Let's make word-page unique then. What if many users will add the same word? What if I will forget and add the same word later? Well, let's add main page with most used words.

What if a word has multiple meanings? What about examples? Synonyms? What if word already exists in the system?

Here the backend-end programming knowledge starts asking questions. The sketches and visuals are OK and use front-end knowledge to generate questions but only until we get to API which comes from database. Everything is data, just showed visually thus modelling of database is important. In the next iteration I started actually thinking about it.

Third iteration and ideas for learning mode.

I should leave possibility for accessing the translations from other same-copy book owners. Thus extending the BookCopy model and wrapping everything around Translation model. Not sure about the naming yet because it might not be translation. Initially I just wanted to show meanings of the words.

The problems arrive when difficulty increases. The more real the idea and sketch appears, the closest to finishing it is the more difficult it gets. Mainly because it's a moment to bring it to actual reality which has databases and APIs which need to be taken into consideration.

Digital design

Prototyping things on laptop is fun if I know what to do cause it requires more time, focus and skills then just scratching paper with pencil.

The initial design I made looked more or less like this:

Prototyping with Figma

I still need to improve it with showing modal, new genius pagination and main or general page with words that repeat. I also would like to add on word-modal:

  • "Value translation 💡" which thanks the person who has added it.
  • "Report translation ⛔️" which informs the admin in case someone has added whole phrase.
  • "Suspect translation ⚠️" in case something might be wrongly translated by previous users. This is important in case I will add other users translation.

API is the key

The API I chose for the development after making an extensive research is Oxford API. The problem is that I will not have an enterprise tier which provides definitions of the words so I need to stick with translations. What is more, there is actually no API for definitions for Polish language. At least no that I know of (and I searched a lot). All that makes me think that the best way will be to provide only translation with examples of usage and synonim words (plus some phonetics and addition info).

The API looks delivers information in a particular way:

JSON returning API response from Oxford API

Which makes me dig into how to use Oxford Languages API and learn how I could transform that into my own API request. The biggest struggles I have with nested objects. How to create my Translation model when providing series of nested objects. This could be solved by understanding well the Django framework I am using and how to serialize data to create object out of nested JSON provided in the request.

API Integration

Now it boils down to how put together API with data which will depend on final design.

The final designs led me so far to believe that it is going to be difficult because the functionality is pretty big one. It should:

  • query server for existing translation,
  • have multiple view levels,
  • multiple functionalities for adding data,
  • changing languages,
  • should be owner-accessible only (should not be possible to copy book content)

Based on the final sketches on paper I started coding the database. The whole functionality is basically integrating with Oxford API and save translated words on different pages of different book copies.

a cut from database schema for highlight mode generated by Django

I have added some demo data on localhost via admin panel (that's great about Django). Now I should be moving to coding serializers in order to get an example of data loaded to the:

  1. Main page - where I mostly require amount of pages with translations available for the book copy. One question still remains - how to get a list of most often used words?
  2. Book page - where I mostly require list of words added by the user OR the users hence the ideal would be coop mode which is basically together translating the same book.
  3. Word Modal - where we get translation along with examples and usability flag.

Serializers first

Before I move to integrating with API, which means querying it, preparing and saving - I want to make sure I get my nested structure well at least in GETing objects.

For now it looks fine.

Nested structure coming from my API

Results return list of pages. Each page has a number, list of words and is connected with a book copy through learning - in case we want to load other people's translations from other copies of the same book. Each word has a colour, list of translations and id leading to core word. I have a distinction between a word and pageWord. PageWord and Translations are connected through core word since this is what they have in common.

Not time for the real difficult fun - saving nested objects.

13th of January 2022, I am moving to coding...

24th of January 2022, I have finished version alfa!

And it is amazing!

I have the book that I wanted to read in French, I have the version alfa ready and I am already reading! I must say that it has even surpassed my expectations for a version 1. Now, when I will be adding hundreds of words, I will probably find quite a lot of things (bugs) but I will try to fix them on the fly.

Currently the Trello Card I had for it, already grew from  27 to 42 tasks.

The counter on the card was showing over 440 hours since I started it. Of course it was running all the time, even when I was asleep but the project was in my mind.

This is exactly what happens with creativity. Sometimes to get an idea for something, one needs to sleep or wait or experience. When the project is big, those experiences take time and this time is impossible to measure. That is why it is so important to release creativity under no money dependant circumstances. How a freelancer that is getting paid almost nothing on some upwork, could produce anything of value? Ideas, quality, innovation. It is so difficult to measure all that. Especially in a world that is running so fast and tightens and tightens and tightens its processes by calculating efficiency, progress, value with simple digits, without stopping and giving it a calm, wise, thoughtful, critics.

Moving forward - let's talk about something positive. The final product.

Let's have a look.

But before that, let's have a look at the book itself.

Aneantir by MH

Judging by his last interview and art approach with which he treats books, I think he would have really dislike what I am doing with it. I personally love the fact that they are colorful. I still need to read a book that has been already highlighted and shared with me by someone. Maybe by then I will change my mind but that does not change much. I am following reading at a quick pace thanks to the learning mode.

Ok, now to the point: - learning mode

From left to right:

  1. You see the main screen that opens on scanning the code present on the cover. There are 3 options with nice, clean, welcoming icons that show: notes, learning mode, quotes.
  2. The default page just on entering learning mode. It updates the language from the book informations, clears everything and prepares default highlighter since yellow is what people usually use.
  3. I love colors and I highlight everything in the color of the book's cover so you see here that a color can be chosen. It's just a tiny fun element. On typing the word Neant, we already have a definition and automatic translation which we can select.
  4. We can change the color and select a definition out of the suggested once.

Now let's click the word list on the top, wide toggle button. - learning mode - words list

Again, starting from the left:

  1. Nothing present on the 10th page, no words.
  2. Some words added by me on the 11th page.
  3. More words on the 12 page. You see at the bottom buttons to generate Flashcards sets out of all the words explained so far in the book.
  4. Popover with details of the translation. There is also place for example phrases, edit mode, user feedback with avatar (to see who was reading) and others. But those are maybe future things.

For now it works and after reading the book, it will be I think very well tested.

I then will write a tutorial for those language learners who love paper copy books.

I think that there might be 2 or 3 in the crowd of billions.

To you and to all others I say thank you for reaching this far. You may have a look at the manifest that explains the reason of doing all this.