Amateur in opensource - lessons learned for 3 years

Published on January 13, 2019

Amateur in opensource - lessons learned for 3 years

    A long time ago, in 2014, I made a small utility for myself in order to translate the C # model into TypeScript code. She saved me a lot of time and nerves. And so, in September 2015, I decided to arrange my "experiments on the knee" in some kind of digestible form and pour them on GitHub. So began my amateurish participation in the development of open source software. As time went. And so, yesterday in the repository with this project, finally, the anniversary, three hundredth commit has appeared. In connection with this significant event, I would like to share my amateurish experience about what you will have to face if you suddenly come up with the idea of ​​developing something "for the benefit of the development of the industry." I will state some figures, tell some cool stories, and share my impressions of what it is to write and maintain an opensource-project withoutmoms, dads and loanscompany support, payment and ... and free time. Come under the cat, sit down, we begin.

    "Do useful"

    To begin with, there are over 90 million repositories on GitHub . Some of them are known, some are not very, some are generally private. In view of the mass popularity, students began to use Github for assignments, teachers for lectures, authors of books for tutorials, and even enthusiasts for legislation . Just imagine what a fucking abyss of code and projects it is! However, I put a bottle of brandy that if a journalist gets attached to you right now and asks to name known repositories, then you will call it offhand ... well, somewhere around 15-30. What does this mean? So this is what GitHub is a huge universe of software products, most of which, I am sure, are known only to their authors. And maybe 5-10 to their friends.

    Becoming more or less noticeable in this crowd is quite difficult, I tell you.

    Even if you steal the data of bank cards of all-all users of the world and put them on GitHub, then I am sure that you are banned and prosecutedThis is just no one will notice . Why am I telling such obvious things, you ask? But ... damn they are not obvious! Especially for the author of these lines :) Especially 3 years ago. Then I naively thought that it was enough to do something really useful, specify tags, write a README and people will find everything themselves, download everything themselves. Well, seriously, since some kind of left-pad , consisting essentially of 47 lines of code, scored a thousand stars, my thing, which objectively simplifies development - well, 300 will be typed, right?

    Mmm ... no. Unfortunately, this does not work. The left-pad was created in 2014 and was decidedly unknown to anyone until the famous events of 2016 . If you look at the graph of the distribution of stars, we can observe a rise almost at 90 degrees just at that very ill-fated time. From this marvelous story, there are obviously some sad conclusions:

    Without proper marketing, your best idea in the world will go unnoticed.
    Black PR is also PR.
    Not always a crazy number of stars suggests that the project is good.

    But it is not all that bad. If you have already prepared to get depressed about this, then my advice to you is to set aside the handkerchiefs and the pillow for sobbing.

    Better do something useful. First of all - useful for yourself.

    Estimate without any software product life is not a joy. Here to you personally, reading this post. What application, framework, servicehellyou are lacking? At your work or in your daily life. Estimated? Fine. Hammer in Google and if the issue at your request blows melancholy and inaudible - go ahead! Get a repository, open IDE and write. Write what you dreamed about, collect and share. The solution is simple - if specifically your project is beneficial for you, then around the world, most likely, there will be a thousand or other people to whom it will also help and who will be grateful to you. I am sure that for the first time such an audience is more than enough for you. Then it's up to you to bring your work to all these wonderful people and not to spill it along the way.

    PR without pants

    I heard, in some companies there is such a practice. If at the interview, the candidate mentions his opensource project, then the very next paragraph begins to crucify him on the topic “how many stars?”, “How many downloads?”, “How many live projects are used?”. So, I declare to you responsibly: such questioners should be sent to the stump with a quick and decisive movement of the language, get up and leave the interview, forgetting forever the name of this company and friends about it. If a manager (or someone interviewing you there) comes up with such a question, then with a close to one hundred percent probability, he never dealt with the development of free software, he hasn’t heard about marketing, and, in general, gives little importance to the sounds that he himself publishes . Work with this will not work.

    Sadly, but apparently, a fact: according to my observations, companies are somehow behind popular and large-scale projects.

    For example, in the form of direct financing of development: if the project is done during working hours, then it is de facto paid. Yes, yes, even if you have “Friday-for-your-projects” - what, do you think it is not in the budget? Or in the form of information support (articles, conferences, videos). Well, or in the form of support "staff", a la "Vasya, go help Oleg to make a feature in his project." And this is not to talk about quite frank cases of funding opensource development like EntityFramework or .NET Core, when there are entire departments involved in such projects. Or all at once (here the conspiracy therapists may ask the question "who benefits from it," but we will come to this).

    To me, from the resources, the company provided only free testing of my work on living people. And no, I'm not complaining - I myself insisted on it that all rights and control over the development remained with me. And for the company with which the contractor relationship has been connecting me for the last 4 years, IT is not so much a core business. Uncomfortable somehow distract people. In general, the bottom line is as follows: the company treats with understanding, supports morally and provides its system for checking and running the project on live users. In exchange, it receives the priority right to support and bug fixes, as well as consultations, implementation and staff training. Bozhechki, I speak in the words of a major integrator, although in my project there are only about 5 thousand lines (without tests).

    Lyrical digression about the help of companies

    Ой, а был ещё такой интересный случай. У меня куплена 2015 студия, 2017я Community Edition, но помимо этого я пользуюсь ReSharper-ом от JetBrains. И он у меня тоже куплен. Помимо прочего, у меня так же есть аккаунт на Azure, где за символические деньги размещён простенький веб-сайт с информацией обо мне, ссылками на проекты и документацией. Так и вот. У JetBrains есть программа бесплатных лицензий для опенсорс-разработчиков. Ну я и думаю — дай, заапплаюсь. Копеечку, но сэкономлю. Будет у меня подарочный ReSharper. Почему бы и нет? Написал, значит, письмо на требуемый адрес. Мол, так и так. Делаю такой-то проект, вроде как опенсорс. Дайте, мол, лицензию. В ответ приходит такое:

    We have checked your Open Source project to see if it meets all the requirements of JetBrains’ Open Source License Program.
    We have to inform you that according to the rules of our program, if the project provides any paid services (training, consulting etc), we cannot issue free licenses on general terms.
    As I can see on your project’s website it does provide some commercial services (, therefore, unfortunately, I won’t be able to provide free open source licenses for your project.

    Короче, опуская подробности. По существу им не понравилось, что на своём сайте (который посещают 3,5 анонимуса) я написал что готов предоставлять коммерческие консультации и индивидуальную коммерческую поддержку по любому своему проекту (из двух, хе-хе). Ни стоимости услуг, ни каких-то конкретных условий — просто, мол, "если вдруг надо — вы пишите, договоримся". Как вы понимаете, предложений, конечно же, не поступало. Что я сотруднику JetBrains и попытался объяснить в непродолжительной переписке. В конечном счёте получил такой ответ:

    If your project does not provide commercial services then please remove the commercial section from the website and let me know once you do it — i will then issue an open source license for you.

    "Ну ни фига себе" — подумал я — "это значит получается я должен удалить с сайта информацию об открытости к коммерческим предложениям в обмен на 200 долларов (стоимость лицензии на ReSharper) в год?! Нет, ребята, это так себе предложение. Спасибо, не надо". И не стал продолжать диалог.

    Тут, конечно много вопросов: во-первых, сколько маны небесной рекомендуется употреблять во время разработки, чтобы не потолстеть? если мой проект используется в компании, в которой я работаю, но разрабатываю я его в свободное время — это считается оказанием коммерческих услуг? Во-вторых: если мой проект не используется в бизнесе — он получается бесполезен? JetBrains готов финансировать бесполезные проекты? а если я указываю свой opensource-проект в резюме и это повышает мои шансы быть нанятым — это же тоже коммерческое использование? Так может его ещё и в резюме не указывать? А вот ещё бывает что компании поддерживают контрибьютора информационно — это же тоже деньги просто в другом виде? Необходимо уточнить! Совсем ничего не понимаю.

    In general, as you understand, I stood up to the task of promotion and PR alone. The very first idea that came to my mind was to write how to use it all. Here I decided to cheat and combine the useful with the useful - I wrote the first article about RT for Habr (for which a UFO was invited). The idea was not so much in the "I dodel" -piar, but rather in placing on the Habré well, at least some Russian-language documentation. My colleagues are still from Russia, so they needed at least a small manual, but I didn’t want to explain to everyone in the correspondence or voice the same thing. So the first three articles were born, which were rather coldly received by the audience. This is understandable - it is unlikely that they were useful to someone from the habr-community, so I don’t worry about it.

    About documentation

    The idea that it would be nice to give people some knowledge about how to use my framework did not give me rest until I finally formulated it in this form:

    The documentation is such a thing: it is useless without the project code, and the project code is useless without it.

    Great idea, except that I knew very little about writing documentation. In addition to memchiki and jokees about undocumented code, it was clear to the backside that it was necessary to describe verbs for the description of methods, and it is not necessary to document the designers. On this my knowledge, perhaps, exhausted. I made the first version of the README , filled out the project description and began to think.

    How does an amateur approach to writing documentation? Of course, via doxygen, what else can a programmer think of? No sooner said than done. I set myself to siphon off XMLDOC (this is like javadoc, only in C #) so that the build in Release does not give out the "no missing comments for publicly visible members."

    To publicly visible members, the C # compiler refers to types, methods, and properties that are visible "outside" when other users use your assembly. In general, everything that does not internaland does not privateunderstand C #. Currently, the statistics are as follows: in the project there are about 150 public types (total - about 250), which contain a total of about 700 public methods and 260 prop. And all this must somehow be explained to the user. I was despondent, but sat down to write.

    After the first 20 documented recordings, I noticed that my writing potential was somehow searching, and my vocabulary was drained. How, tell me, in one sentence, to formulate what affects the class field? It is advisable not to use the passive voice, the involved speed and cumbersome descriptions of the circumstances of time. I began to respect technical writers. Guys, really: take care of technical writers - they really have a dog work. It dawned on me: it is possible to peep how to solve the problem with perperty in MSDN! This action gave me an absolutely wonderful verbal construction.

    Try to begin the description of the class property with the words "Gets or sets whether ..." - in some magical way, the ending itself comes to your mind!

    In short, it became easier.

    After 30 documented classes, I began to realize that something in my project was too dofig of these very "publicly visible members." The documentation process was discontinued, the code was carefully analyzed for what the user really needed, and without which the user would manage. As a result, about a third of the trash that needs to be documented, the modifier internal( even as packagein Java) has gone down in an even layer . This is how true professionals solve documentation problems, yes! Hide extra. In short, it became easier.

    By the time about half of the compiler warnings about comments were repaired, I was almost depressed.

    It turned out that standardized comments in the code are not enough! And doxygen will not save.

    The fact is that in the harsh reality, the user looks at the reference footcloth, carefully generated by doxygen, and sees 150 classes, interfaces and enums that the devil will break his leg as related to each other. And stuff examples of use in each class and each method - you can drown it! By the end of the writing of XMLDOC, I came up in full confidence that it would be impossible to do without “human” documentation. Suddenly, it became really bad.

    Having finished with XMLDOC, I decided to see how the documentation works in already existing projects and dwell on the version that I would like the most. The choice fell on the seemingly wondrous documentation to Autofac, made on the ReadTheDocs.ord platform . I was impressed by the reStructuredText format. The decision is made, I sat down to write a documentation plan. And imagine what? It turned out a complete garbage. In what sequence to state? How will the user read this? What first, then what? What should links come from? A ton of questions and now drafts of plans fly into the urn.

    I decided to ask for help and turned to a wonderful chebureque, which at that time was just starting its big business in the provision of technical documentation services. By his efforts I was singled out a student who wanted to learn the secrets of the art of a technical text. In the course of several weeks of work, the student was tortured with descriptions and calls about what and how to write. The realization came that the project is very specific and requires knowledge of many technical details. If I start to describe them with text, then ... Then in the end it will be damn it, and there will be documentation! And if I speak in a voice and control the process, then it will take at least half a year to work, discuss, agree and review. So much time and free money to pay for student work, I simply did not have. So the latter was rewarded for a month of effort and sent with peace and blessings.

    I was left alone with the understanding that good project documentation is long and expensive. To make it the efforts of one person in sane time is virtually impossible.

    This story ended in the best traditions: the author psihanul, took the github wiki built into the repository and just began to write in pure markdown what he thinks about the project. As soon as everything that came to my mind was written, I rearranged the blocks of text in a sequence that seemed to me correct, divided them into pages and poured them into GitHub. Hai will. That's how we live.


    I now know about this picture. But to rewrite something, to be honest, there is simply no power. I state that in matters of documentation I gave up. Sadly

    Lack of users and conference

    Lack of conference and users

    The time has passed. I released 9 more versions of the package in NuGet, fixed bugs, added functionality. So, it was 2016, and again I thought that it would be nice to tell someone else about my project. At that time I was in Estonia (because why not?) And a brilliant idea struck me!

    Why not go to the conference and show there what I have in the repository?

    The issue of Google at the request of "european it conferences 2016" puzzled me. Nowhere did not talk about C # and TypeScript. Everywhere web, mobile devices, robots, cryptocurrency, IoT. Topics are as abstract as possible, wording as wide as possible. So much and there is no place to go! After walking around the sites, reading the announcements and headlines, I was surprised to find that a huge number of conferences are literally “about nothing”. The descriptions read something like “challenges to business in the age of ubiquitous Internet,” “cloud technologies in the modern economy,” “the evolution of commerce at the turn of the century.” Truly, paranoia and futurology! The names read the silent request "hey, somebody, please come and tell us what will happen to all of us!" But oh well.

    Having traveled considerably and read everyone, I found an inconspicuous, almost casual conference DeveloperDays 2016 in Poland. I wrote to the organizers and asked - is it possible? Pretty quickly, one of the organizers answered me, a guy with a difficultly made name Křishtov and said that he could. Only, he says, we have a rule - everyone who registers with a listener chooses 10 speakers of interest. Pass this selection - we will give you a ticket and pay for accommodation. I sent a description, I was also asked to photograph, and I waited. After a couple of weeks of silence in the mail, I made a bold conjecture that I was not chosen. I wrote to Křishtov and he confirmed my guess. He says your topic, unfortunately, interested only two people.

    - Don't be upset - Křishtov tells me - come anyway.
    - Yeah, right now! I do not figs in Krakow dragged! - ... I think. But I write, of course - Nothing, everything is in order. Good luck with the conference.

    Unforeseen consequences began after. The count of downloads in NuGet unexpectedly went up, and about 10 stars were added to the project. Of course, from users with suspiciously Polish names and surprisingly Polish surnames. I would even say catastrophically Polish, because these people began to create issues! What is strange: almost no bugs. More and more they asked for features and asked questions that were not covered in the documentation. As a result, after the third faq badge, assigned to the next closed ticket, probably the best marketing strategy for its project came to me.

    StackOverflow! Damn, this is brilliant!

    I signed up and went straight ahead and found three questions about exporting C # classes to TypeScript, which I immediately responded with a brazen self-PR. And about a miracle - they put my answers to the pluses! Urgently, the README was rewritten to be more intelligible, and a bit later the Support policy section was added. It was stated that from now on all the questions are accepted on StackOverflow on a particular hashtag, the creation of which I asked one of the incoming users. Because well, really convenient format for storing the FAQ. I subscribed to the hashtag via RSS and enthusiastically set about supporting the project.


    After RT lit up on StackOverflow - the stars started to slowly but surely flow into the project. With from people from completely different places and companies! The stargazers list featured people from Barclays and Microsoft. Geographically, the stars came from different parts of the world - the United States, Denmark, Germany, Romania, Canada, Australia ... And even Belarus! In secret, I’ll say that at one time in Insights it was obvious that some pages of documentation were persistently observed from some American company from JIRA.

    On StackOverflow, I received a few questions that I promptly answered, for which I was rewarded with pluses and a reputation. Nicely. Issues periodically came bug reports, which I tried to repair more or less quickly. Unpleasant At some point in the project tests appeared. I naturally came to their need, not trying to cover with tests anything in advance. These are simple but proud regression tests in which I reproduced the sent bugs (unfortunately, not all - for technical reasons) and repaired, closing the bug with a link to the test.

    TDD is convenient, but only from a certain stage and only to control the regression.

    And you know - people are still pleasantly surprised when their bug in the framework is more or less efficiently fixed. This is clear from likes and short but heartfelt thanks like


    Several small but good pull requests were received. Almost all of them were Smergins in the master (albeit with changes), which added contributors to the project - there are already as many as 10, although 99% of the code is still mine.

    The biggest support problems were with several conflicting feature requests, as well as the fact that both C # and TypeScript are changing quite quickly. The ecosystem is developing so fast that I literally do not have time to roll out updates!

    During the existence of RT, dnx managed to leave, .NET Standard will appear, go through 3 releases of .NET Core, get out about 20 releases of TypeScript, and for all this stuff I had to quickly release updates in order not to fall out of the trend.

    And yesterday I learned that one of the competing frameworks has not yet released support for .NET Core :)

    And here I am

    Sensations, oddly enough, alarming. Despite all the thanks received, to support such a project and feedback from users is quite difficult (who would have thought!). Yes, I am doing a useful job, but ... why should I? Yes, this is experience: the experience of communicating with the audience, writing documentation, taking public responsibility, planning. Technical experience in the end (I gave up this .NET Core, but the woman bought a pig). However, what does this give in addition to experience? To be honest, nothing.

    Over the past 3 years, no one has been interested in this project besides its direct users. Employers? Recruiters? Pha! Do not tell my sneakers. The link to the project sticks out in all profiles, but is not mentioned in any letter with a job offer. As if it does not exist. And some individuals even asked me to attach sample code to a resume with a zip-archive — that’s how mimicry and invisibility skills are developed in GitHub links! In general, get ready for the fact that in a career plan a small but lively OSS project will not help you much.

    What gives the opensource-project to its author? Yes, in fact, almost nothing.

    Why then?
    I can understand why OSS is needed by companies: they thus raise their reputation out of the blue (opensource as a form of public philanthropy) and increase the availability of their technologies for potential users (increase coverage). Microsoft's interest in OSS is indicative - through .NET Core and "Microsoft loves Linux" users are actively attracted to MS-infrastructure, in which there are many interesting commercial products - Azure in particular. And as for me - they have the right! The goal is noble, the means are legitimate.

    Companies earn on opensource. Yes, yes, for example, Percona takes mysql, collects custom builds, fixes bugs and finishes the features "for the customer". Sometimes, of course, mysql commits itself, and answers questions. But basically it sells its expertise in using mysql for your dark business.

    Countless variegated integrators, as well as small system administrators do not hesitate to sell their services in installing and configuring OSS-software, for example, for office needs. And this is their bread and butter: in many OSS-projects, even with documentation, the devil's leg breaks, and these seem to be dealt with. True, for the coin.

    They also use OSS, all of a sudden, and for political purposes - I heard a story that, allegedly, through the development of Apache Harmony, Sun Microsystems, who now died, was forced to open the JRE source code (I could be wrong, rumors still).

    I can understand why OSS is needed by company employees if companies are willing to pay for such activities. The business is to convince the boss that you are doing a very useful job, “you are making the world a better place” - and that's it. You can get a salary and set tasks for yourself. The company can use this project for the technopiare - show, they say, "look how convenient it works in our company - employeesfrom idleness They create their own projects, and we are open to ideas, "etc. And I heard that version of events.

    I can understand why OSS is needed for young developers - to gain industrial international experience, to show themselves. Here the best option is to choose some existing project and thoroughly commit it. Participate in discussions, enter the user group, community, answer questions, show support. With such experience, it is good to go for an interview in serious companies - you will know what happens in live development, it is more interesting to answer questions at the interview. Yes, and English practice in the end. You can proudly hang up the badge "member of something user group, contributor".

    It is almost impossible to make a large and somewhat well-known OSS project from scratch, in modern realities , as it seems to me. That is why I call my experience amateurish.

    And the point is not that you are a bad programmer. No, the programmer you are most likely honest and good. But the marketer, technical support officer and technical writer in one person - most likely not.

    In order for the project to work seriously for your career and advertising goals, you need to build a noticeable community around it. And in order to build it, you need either money, or a huge amount of time and energy, with which, again, you have no opportunity to throw away, otherwise you will have significantly less money and, as a result, food in the refrigerator.

    It seems to me that the only place where free products made by singles from scratch are really waiting for the target audience is perhaps linux. Especially the wondrous world of "desktop" Linux. The system is not that very popular, many of which are not from the software - users are welcome to any development. However, companies have already brought their resources and money there. In general, it is somehow even offensive that opensource has turned from a “creative impulse”, a bold experimentation and the possibility of self-realization for developers to one of the business and marketing tools for companies. But the market is the market. In the end, the money spent, the results are. Without such help, open source software would be much worse than it is now.

    But let's just be honest. If some commercial structure declares that it “deserves the support of the opensource”, implying increased spiritual purity and a benefactor, this is in most cases a blatant lie and a distortion.

    Companies do not do what is not profitable for them.

    Supporting opensource, companies seem to be included in the "imaginary authorized capital" and retain the right to use the side effects of sponsored opensource development for their own purposes - be it marketing, or direct monetization. Therefore

    An alarming conclusion: the usefulness of an OSS project for target users and the usefulness of an OSS project for a company sponsoring it are often diametrically opposed. And the sad reality is that in order to succeed, the project needs to be useful primarily for its sponsor. Not for users.

    No, I do not call, of course, for the communist revolution, to "take away and divide" and "banish all commerce from the opensource." I urge to take off rose-colored glasses and not to think that if the company supports OSS, then this is gratuitous care for the industry and is done from the great kindness of the soul. Not at all. I would say that it is profitable for a company to invest a penny on the condition that its ears will stick out from the project in all directions. And there is no charity in this. As soon as this condition is violated, the company loses all interest to the project. And if there is interest, then rest assured - the company will get its gesheft. But will you get it? That is the question...

    Okay, let's say goodbye. Finally, I will give some figures about my project:

    • about 5000 lines of code, 225 classes, 1428 methods, 380 perperty;
    • 43 releases released;
    • 84 issues closed;
    • 10 contributors;
    • 107 stars;
    • 28 forks;
    • 1100 visitors per week;
    • ~ 50,000 downloads-installations in NuGet (approximately 40 times a day);

    Link to GitHub , link to NuGet .