06-18-2010, 04:42 PM
Hi all,
I've been thinking how to simplify and homogenize the docs; and also how to make them easier to create and mantain.
I'm preparing a list of detailed suggestions for your consideration, but the first one is ready:
I suggest for the Syntax section:
You can see and example in the peek page I just rearranged. Note I left both syntax layouts for you to compare. Also the rest of the page is changed to illustrate some of my future suggestions.
I've been thinking how to simplify and homogenize the docs; and also how to make them easier to create and mantain.
I'm preparing a list of detailed suggestions for your consideration, but the first one is ready:
I suggest for the Syntax section:
- to use <freebasic></freebasic>. I think it's easier to write and to read, and it looks nicer and more clear. The current combination of bold and italic is not comfortable to edit (besides, I think their Mediawiki notation is unhandy and hard to read).
- to show syntax variants simply one after another, without "or" or any kind of comment; simply one line of code per variant (no need to mark optional parameters). No text in the section, only clear code with proper parameter names.
- to use lowercase (it's a fact it's easier to read and to write) for everything (keywords and parameters).
- to use camelCase for parameters with compound names (they cannot be reserved words anymore, because of <freebasic>).
You can see and example in the peek page I just rearranged. Note I left both syntax layouts for you to compare. Also the rest of the page is changed to illustrate some of my future suggestions.
Marcos Cruz
http://programandala.net
http://programandala.net