Project documentation or Mom told me ...
After reading and discussing Habratopic on pre-project documentation , all sorts of thoughts began to swarm in my head. First of all, of course, related to my hobby project JuffEd.
We return to the present. November 2008th year. At the moment, the editor is able to far from everything that I would like from him, but once again looking at the source code with an eye on new features (and improvement of existing ones) I was beaten by despondency. Hosspadi, who wrote this, sho you here, my dear, freaked out ... = \
In general, there is a small redesign. Most of the components function as they should, and I still don’t like it, as I did it elegantly (modestly, but true :)), but the main “engine” needs to be revised. And here the full-length question arose: “so ... and how will we redesign this business (and most importantly, test the result), if we don’t know at all what it can do?” Or rather, we know, but about. And from memory, of course, we will not list all the features. And if we don’t list them, we’ll not be able to check whether everything works after redesign. And if we fail, then something will definitely not work. And if something will not work, then users will be upset. And maybe get angry. However, an evil user is not at all what we want to get.
')
The causes of the incident are clear. The project was developed according to the scenario “something was freaked out, it seems to be working” - “oops, here is another thing to add” - “Wow, they sent a ficrequest! Let's do what problems? ”-“ Oh, another ficrequest ”-“ Oh, bugreport! Let's fix it ”-“ Oh, fichrequest! Let's do it. ”- ... and in the end we have what we have. Neither the list of functions, nor the description of the architecture, nothing else. Even classes are not really commented. Not to mention user documentation ...
Probably, similar problems are characteristic of many “just for fun” projects, but this does not change the situation: this particular project requires increased attention in the field of documentation, which is what I intend to do in the near future.
Lyrical digression:
The JuffEd project was born completely by chance, in one dispute about 1.5 years ago on the topic “how can I write a gui on a cinplus?” The man was slightly stuck in the MFC / OWL / Win32 API times and didn’t imagine that you can write gui in C ++ easily and naturally, yes also cross-platform. JuffEd, the editor with the simplest functions and the simplest syntax highlighting, written in Qt4 was born as a demonstration. The person was impressed, realized the gaps in education, and the editor was almost sent to the dump (because he didn’t stand out for anything special, didn’t know much, and was made hastily), but then I discovered that they use it. Few, very few people, literally a few, but enjoyed. It was a pleasure, so I decided not to throw it, but to develop to the best of my abilities and see what it would take.
We return to the present. November 2008th year. At the moment, the editor is able to far from everything that I would like from him, but once again looking at the source code with an eye on new features (and improvement of existing ones) I was beaten by despondency. Hosspadi, who wrote this, sho you here, my dear, freaked out ... = \
In general, there is a small redesign. Most of the components function as they should, and I still don’t like it, as I did it elegantly (modestly, but true :)), but the main “engine” needs to be revised. And here the full-length question arose: “so ... and how will we redesign this business (and most importantly, test the result), if we don’t know at all what it can do?” Or rather, we know, but about. And from memory, of course, we will not list all the features. And if we don’t list them, we’ll not be able to check whether everything works after redesign. And if we fail, then something will definitely not work. And if something will not work, then users will be upset. And maybe get angry. However, an evil user is not at all what we want to get.
')
The causes of the incident are clear. The project was developed according to the scenario “something was freaked out, it seems to be working” - “oops, here is another thing to add” - “Wow, they sent a ficrequest! Let's do what problems? ”-“ Oh, another ficrequest ”-“ Oh, bugreport! Let's fix it ”-“ Oh, fichrequest! Let's do it. ”- ... and in the end we have what we have. Neither the list of functions, nor the description of the architecture, nothing else. Even classes are not really commented. Not to mention user documentation ...
Probably, similar problems are characteristic of many “just for fun” projects, but this does not change the situation: this particular project requires increased attention in the field of documentation, which is what I intend to do in the near future.
Source: https://habr.com/ru/post/45417/
All Articles