Rick Barnes wrote:
Thanks for your review, this is a massive chapter with room for manyAbsolutely, the occasional mistake with something that long and complex is entirely inevitable and understandable. :)
typos and formatting errors.
What we are tying to do is explain the functions in a way that everyoneI can understand that entirely, and I do see where you're coming from. However, I don't think that it is necessary to... 'disadvantage' people who are familiar with traditional syntax. It doesn't *harm* understanding to have italics or brackets, and anyone who actually needs to learn about it can just read on to the description (which they really should be doing anyway; someone who is technical and just wants to remember the format might just glance at the first part and move on, rather than having to read the text to see what is optional) and they can very quickly see (and work out after a couple of examples) that the italic parts are the bits they should be changing, and the square bracketed parts are the bits that are optional. I also only chose to implement the bracketing system because one of the examples was already using brackets, and it gave me the idea to continue to use this format, since to the initiated it makes readability a lot easier. In fact, the brackets are one thing, but the italics are far more generic and important, because they indicate that there is simply something special or worthy of note about the text. In many respects, this is a better thing, since it helps to develop good understanding of exactly what it is they're reading, and when they apply that to more technical things, they won't have a steep learning curve to get up to speed on things that aren't as verbose with the documentation as we are.
can understand...you and I (being programmers) are used to brackets and
other forms of emphasis in function syntax, but many spreadsheet users
are not. My opinion is to leave the syntax as simple as possible and
explain it fully in the description. I am sure many users will not
understand why an argument is bracketed, but they will understand it
when they read the description.
Alan
