You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This is not likely the proper way to post this comment, but I am presuming that whomever owns/manages this documentation facility will receive some notification. Hopefully, you will be able to read my comments and then simply delete it so that it won't clutter your work.
I strongly feel the need to comment upon the high quality of the work being shown in the evolution of this Cookbook. I have decades of experience in dealing with the frustrations that arise wherever the documentation of new technology is required. Indeed, since I have spent about 12 hours per day and night for each of the last ten days in trying to get my arms around so many new pieces of technology from the Haxe ecosystem, and since much of that effort has resulted in incomplete and/or out of date snippets of information, that finally coming upon this work has truly been refreshing.
Several key ingredients are necessary to getting tutorial documentation right. The first key ingredient is the absolute understanding that the top-level stake holders must make. Where such stake-holders mostly come from the software engineering ranks, there is all-too-often a failure to understand and a failure to insist upon the timely release of documentation amidst the always-present pressure to release some new block of code. The second key ingredient is recognizing that the old fashioned ability to craft words in well-organized paragraphs never goes away -- the short-hand acronymiphomia that we have as writers of code, can never be used as some sort of a stand-in for quality writing by those dedicated to that profession. The third key ingredient comes from watching how these sorts of on-line references have evolved since the folks at Sun released the first java docs, but especially outstanding has been the manner in which Adobe evolved the living ActionScript documentation repleat with meaningful examples.
You are on the right track with what I have read so far and I hope you will be given the mandate and support to aggressively work towards a higher percentage of the total toolkit being properly documented. The toolkit, of course, has achieved earned respect for what it represents, but unless its key features can be properly conveyed to newcomers, its capture of the marketplace will always remain small. In the final analysis, engineers, marketeers and documentation specialists work together to get on paper and in a few well-contrived graphics the important facts that a user must master in order to move forward in developing applications with that toolkit.
The text was updated successfully, but these errors were encountered:
Its all community effort of course, but since I feel responsible you made me very happy with this comment, since most points are correct (like getting all snippets of code in one central place), I hope we can continue change this. Thank you so much!
I'm curious why it took you so long to get to this cookbook. It is linked from several places on all Haxe websites and does quite ok in Google. I would love to improve that.
Btw feel also free to contribute yourself. It's very simple, just edit some markdown files. Small bits of info help already.
Sources:
@dstrekelj
This is not likely the proper way to post this comment, but I am presuming that whomever owns/manages this documentation facility will receive some notification. Hopefully, you will be able to read my comments and then simply delete it so that it won't clutter your work.
I strongly feel the need to comment upon the high quality of the work being shown in the evolution of this Cookbook. I have decades of experience in dealing with the frustrations that arise wherever the documentation of new technology is required. Indeed, since I have spent about 12 hours per day and night for each of the last ten days in trying to get my arms around so many new pieces of technology from the Haxe ecosystem, and since much of that effort has resulted in incomplete and/or out of date snippets of information, that finally coming upon this work has truly been refreshing.
Several key ingredients are necessary to getting tutorial documentation right. The first key ingredient is the absolute understanding that the top-level stake holders must make. Where such stake-holders mostly come from the software engineering ranks, there is all-too-often a failure to understand and a failure to insist upon the timely release of documentation amidst the always-present pressure to release some new block of code. The second key ingredient is recognizing that the old fashioned ability to craft words in well-organized paragraphs never goes away -- the short-hand acronymiphomia that we have as writers of code, can never be used as some sort of a stand-in for quality writing by those dedicated to that profession. The third key ingredient comes from watching how these sorts of on-line references have evolved since the folks at Sun released the first java docs, but especially outstanding has been the manner in which Adobe evolved the living ActionScript documentation repleat with meaningful examples.
You are on the right track with what I have read so far and I hope you will be given the mandate and support to aggressively work towards a higher percentage of the total toolkit being properly documented. The toolkit, of course, has achieved earned respect for what it represents, but unless its key features can be properly conveyed to newcomers, its capture of the marketplace will always remain small. In the final analysis, engineers, marketeers and documentation specialists work together to get on paper and in a few well-contrived graphics the important facts that a user must master in order to move forward in developing applications with that toolkit.
The text was updated successfully, but these errors were encountered: