Arkadiy Vertleyb wrote:
"Edward Diener" <eddielee@tropicsoft.com> wrote
Arkadiy Vertleyb wrote:
"Paul Giaccone" <paulg@cinesite.co.uk> wrote
"Essentially, Boost needs to sell itself as something that no C++ programmer would want to be without. Think how the adman would write it: "C++ getting you down? Spending hours tracking down that memory leak? Then try Boost! It will change your life!" Well, maybe not, but something along these lines would certainly go a long way to showing why anyone should be using Boost. While I completely agree, I can't help but mention that people fluent in this kind of language What kind of language ? Do you mean writing correct English ?
No, I don't mean English.
If one's primary language is not English I can well understand this, but if one's primary language is English it is that person's own fault that he/she can not write English well enough to be understood by others.
Being very fluent in English myself, I have volunteered in the past to help other Boost developers write better English
This is very much appreciated...
but since no one has ever taken me up on it, I do not think it is acceptable to claim that the inability to write English is a stumbling block to writing decent documentation.
Well, this is not about documentation... This is about the "language" sales people use to convince kids that Coca-cola and chips is the best food in the world. I believe this kind of language is pretty much international.
It may be "international" but it is worthless for serious programmers. What Boost might have is a paragraph, or two, on each implementation explaining to a programmer what the main functionality of the implementation is about and why one might want to use instead of current solutions which are part of either the C++ standard language or C++ standard library. I think this could be done in general terms without resorting to empty market hype, and would be an effective means of telling the programmer about the importance of a particular implementation before he delves into that implementation's specific documentation. While much of the Boost documentation is excellent, there is a tendency in some of it to start explaining details before a good general explanation is given, and this possibily results in discouraging programmers from using the implementation.
I do agree with Martin Wille that this kind of advertisement may have a negative rather than positive effect, especially when the developers are concerned.
If it's a sort of marketing hype, I agree. But there is room for a good general explanation of a library which sticks to technical elements and useful, practical functionality. There's no need to sell Boost but there could be a better way to make the general information about each implementation more easily understood. Whoever were to write a good general description of a particular implementation, if it were not done by one of the programmer's of that implementation, it would need to be signed off by one of them before appearing on a Boost web page.