Discussion on MQL4 documentation - page 8
You are missing trading opportunities:
- Free trading apps
- Over 8,000 signals for copying
- Economic news for exploring financial markets
Registration
Log in
You agree to website policy and terms of use
If you do not have an account, please register
Everything is understandable, the documentation is there, the examples are there, Rosh has written everything.
The only thing I'm not satisfied with are the examples in the documentation. So many of these examples have already been written here on the site, and the documentation is still the same - dumb :(
I propose (for the third time, I think) to add to the online documentation on the site the possibility to add one's own comments. This is successfully used in other IT technologies.
Here is an example of such a function description: basic, plus ready pieces of code below third-party developers - take and copy.
For example, there was an error with an unspecified identifier and we have already corrected it:
Jhonny wrote (a):
By the way about documentation, I noticed some strange thing when I press F1 on OBJPROP_FIBOLEVELS property in the documentation, something goes wrong or rather almost nothing happens.
But if you want to have the most detailed documentation for all the cases, unfortunately we cannot do that. Inserting the MSDN analogue into the terminal will be difficult. No matter what we write, there will still be questions. And even having articles, a code library, a forum and a search engine for all this stuff won't always help.
The topic of this thread has made me clearly formulate a long overdue thought. Theoretical approach "give me a good documentation/book and I will change the world" is not enough. It takes practice with mandatory and independent stepping on rakes.
Case study from our practice:
We have been improving the methodology of software development for a long time, and we are also getting ready for ISO9000 certification. For the last couple of years we have purchased dozens of books on the subject, re-read a lot, all of them agree on the necessity of implementation. But theory is not enough. You have to get to grips with it and do it. Which we are doing step by step.
It's the same in business. If you read only books, it all seems simple - "believe in yourself, shook up, opened a business and everything went on. Life is different.It's difficult - after reading books your head is a mess. It is the right time to go out and shout "documentation is no good". Immediately the thought "let's call the consultants" and let them do everything for us here. But reason tells us that we have to understand and change things ourselves, not just read the consultants' watery report.
Our position on documentation:
That is to say, our educational task is much wider than the simplest built-in documentation. For example, yesterday I flew in from Shanghai, where we opened our office to promote MetaTrader in China. There will be major changes to the Chinese part of our sites in the coming months.
Take a broader look at how we are doing it.
I propose (for the third time, I think) that the online documentation on the website should allow you to add your own comments. This has been used successfully in other IT technologies.
Here is an example of such a function description: basic, plus ready-made pieces of code below from third-party developers - take it and copy it.
We continue working on the MQL4 site and have a lot of ideas. Tomorrow we will release the beta version of the new editor for the website. Then there will be a new version of the advanced "Related Topics" function.
Of course I saw the comments later, but the article I wanted was almost at the top, that is why I have not noticed it immediately.
I want to say one more thing, this topic often sends newbies to Rosha articles, but I also often visit it, but I haven't done it for a while, because Alpari's site has changed a little and all links from here 'Rosh's articles: MetaTrader 4 experts' lead to 404 error. So I have to correct these links.
Yurixx, what exactly is wrong with the documentation? Please give us a clear indication of the errors and we will fix it.
If you want to have the most detailed documentation for all occasions, unfortunately, this will not work. It will be difficult to insert MSDN analogue in the terminal. No matter what we write, there will still be questions. And even having articles, a code library, a forum and a search engine for all this stuff won't always help.
The topic of this thread made me clearly formulate a long overdue thought. Theoretical approach "give me a good document/book and I will change the world" is not enough. It requires practice with mandatory and independent stepping on the rake.
Our position on documentation:
There must be a chapter describing (as alex_ant wrote) the mechanism of operation of an MQL-program. This is something that every trader who is new to programming can understand even before learning the language. This description must be tied in with the process of trading, and it can also explain the difference between indicators, scripts and Expert Advisors, how they behave in relation to the tick queue, to the trade server, to each other, etc.
More attention should be paid to the structure of MQL-program, its main components - the init(), start() and deinit() functions. These functions are the main difference between MQL and other languages, and the documentation gives them very little space, almost only a few lines.
It would be very nice to go through all the entries in the dictionary and not only eliminate mistakes and typos, but also bring the terminology to a common denominator. Very often descriptions of the same or similar parameters of functions and procedures are made using quite different terms and their meaning is not explained. As a result, descriptions are available, but the meaning and use of some parameters have to be studied in an experiment.
It's very important (totally agree with 4x4ever ) to bring examples in a straight line ! The vast majority of examples in the dictionary articles explain nothing and teach nothing. In fact, a one line example is not an example ! In a normal textbook, the example allows you to understand both the meaning of parameters, and the order in which the procedure/function is used, and the result it produces. And for this it is not necessary to write your own program. IMHO: the weakness of MQL Dictionary examples is one of the main drawbacks of documentation.
You have to admit, it's not much.Renat, your firm's stance on documentation deserves all due respect. However, please note that there is not a single item in the points you have listed that directly relates to documentation. They are all good, but the foundation is the material, with which everyone learns and programs in MQL. At present, these are the Dictionary (i.e., documentation) and, secondly, publications on websites. To make the add-on work, you need to make a solid foundation. That is, bring the MQL Reference to the desired quality.
Renat wrote (a):
Yurixx, what exactly is wrong in the documentation? Please give us a clear indication of the errors and we will fix it.
Renat, your firm's stance on the documentation deserves all due respect. However, please note that there is not a single one in the points you have listed that directly relates to the documentation. They are all good, but the foundation is the material, with which everyone learns and programs in MQL. At present, these are the Dictionary (i.e., documentation) and, secondly, publications on websites. To make the add-on work, you need to make a solid foundation. That is, bring the MQL Reference to the desired quality.
So, I understand that there is no clear indication of obvious errors. It's a pity.
I take it there is no clear indication of obvious errors. That's a pity.
Usually in such cases, in order not to strain yourselves:) to search for specific errors, they give a bunch of multi-page references to GOSTs, SNiPs and ISOs, with an offer to bring the product in accordance with the specified list. It's a pity I can't remember the numbers and I don't feel like looking for them, otherwise I'd throw the list at you ;)
It's a joke.
Renat, what new website editor did you mention earlier when planning to launch it?
Renat, what new editor for the site did you mention earlier here, planning to launch?
One of the new features (not included yet) will be inserting video clips. Both your own clips as well as clips from YouTube. Most likely we'll launch the public testing beta on Monday.
Renat wrote (a):
I understand there is no clear indication of the obvious errors. That's a pity.Yurixx, what exactly is wrong in the documentation? Please provide clear indications of errors and we will fix it.
You, Renat, are jumping to conclusions. It seems that you really want to get rid of annoying "critics" without too much effort. After so beautifully proclaimed position of the company, it suggests that in fact behind these proclamations is an unwillingness to listen to the wishes of users. Indeed, MQ itself knows what to do and how to do it, what do users have to do with it.
I can assure you that you misunderstand the situation. I can very well give you clear indications of what needs to be improved. But first, let me make something clear. This phrase, so convincingly marked in red, clearly suggests the following: if you point out errors, we'll fix them, but we won't look through the documentation ourselves. And the phrase "obvious errors" is also suggestive. During 2 years of debugging and thanks to help of this forum members, the number of "obvious errors" was reduced to a minimum and continues to decrease. But still you make it clear with this phrase that you are not interested in information about other errors that are not "obvious". And you're not interested too in bad examples, incomprehensibly written explanations and the like.
Further, do you really want me to give instructions on ALL documentation errors? No Renat, sorry. Your company may not write a manual on MQL - that's okay. But it must revise the documentation on the language. Yes, it must! Who else but the creator of the language must document it? How else but on the basis of this documentation can programmers learn to use this language ?
So, not to be unfounded, I will give you a typical example. If you're not interested in the quality of documentation, you will certainly find why what I've written is rubbish. If there is any constructive element in this conversation, you'll undoubtedly understand what I mean. But you already know what I mean.
Nevertheless, here's an example.
Normally, an index is a variable that numbers the elements of an array. In this case, it is not an index, but an index number. However, from the phrase "Since indexes start with zero, the dimension size is 1 more than the largest index. " neither this nor anything else can be understood. Especially to a beginner.
What do you mean "Since ..." ? Where was this stipulated before? Nowhere! Because this is a specific function and the variablerange_index, which numbers the measurements, does not appear anywhere else. So you just have to say that the numbering of the measurements starts from 0. And the measurement number (not the size !) is 1 more than the largest value of therange_index variable (not "index"). Better yet, don't squeeze it all into one sentence, but explain it all in 2-3 sentences consistently and intelligibly.
The example given in the description is a Handbook classic. What can it clarify? Nothing ! If you, Renat, don't know how it should be, look at the picture in the first post of this page. At least there should be a printout of the results of operations given in the example. And what value did thedim_size variable take as a result ? I know that you know, but do language starters know about it?
And even if it were written that dim_size=10, would it help anyone understand anything? The author of this example, maybe just for humorous reasons, put number 10 in all the three dimensions of the array.
Here is an example of an attitude to writing documentation. Think of an epithet for the word "attitude" yourself.
I wonder how many "obvious" errors you counted here. Not a single one, I think.
But I can assure you - there are many more such articles in the Handbook which contain no obvious mistakes but greatly reduce the quality of documentation it contains.