On Mon, Mar 22, 2010 at 2:45 PM, The Editor <[email protected]> wrote: > On Mon, Mar 22, 2010 at 9:34 AM, Markus Weimar > <[email protected]> wrote: >> I am planning to contribute: >> - tabular API-like function docs >> - concise system pages with a structuring heading here and there >> - usability improvements to boltwire.com >> - making the docs homogeneous and concise and add more textual structuring > > I might only suggest, doing one API like function page first and then > solicit feedback before doing more. > > If we can get the first one right, then it becomes a template for all > the other. Come up with a great idea later, we'd have to change > multiple pages...
Sure. > On a structural note, were you thinking one long page with all the > functions, or putting the chart on a separate page for each function? > If the latter I'd propose we move all the barn pages under the > handbook hiearchy, so we'd have pages like: > > docs > docs.handbook > docs.handbook.functions > docs.handbook.functions.breadcrumb > > I could whip up a bit of code in docs.handbook.footer to retrieve the > code soure at the click of a button when p0=4. It might take a bit of > time to move over all the barn pages, but we could start fresh also, > as I don't think most of those pages have any content. > > This is the direction I'd like to go, but I'm having a hard time > keeping up with everything... First, I would list the parameters for each function above its code. In my opinion a good function doc string tells you what the function does, what the parameters are, and what the function returns. At a minimum. Take breadcrumb as an example: ## TAKES A PAGE NAME AND BREAKS IT DOWN TO A DISPLAY OF CLICKABLE LINKS UP IT'S HIERARCHY. PAGE NAME USED DEFAULTS TO CURRENT PAGE, BUT CAN BE RESET BY PARAMETER PAGE OR #1. OTHER OPTIONAL PARAMETERS INCLUDE SEPARATOR (DEFAULT >) AND NAME=LINK/NONE (DEFAULT TEXT) TO DEFINE HOW LAST PAGE PART IS DISPLAYED. SET TEXT=TRUE TO DEACTIVATE LINKS. USE OFFSET=1 TO IGNORE THE FIRST PAGE PART. USE RTL=TRUE FRO RIGHT-TO-LEFT DISPLAY You need to read that whole paragraph and it's impossible to read caps-lock. What about a custom doc string that can be used by action=help? Think about it: function docs right in your installation without going to BoltWire.com, reading caps-lock or reading source files. /** * Generates breadcrumbs to the current page * * @in separator text: Separator between crumbs. * @in offset number: Cuts out the first n page parts. * and so on... * @example: [(breadcrumbs separator=">>>" offset=1)] */ The help could parse this and you could see what a function does and how to use it with two (!) clicks (help > breadcrumbs). Updating these short function docs would be easy as you update it as soon as you change the function. With such a cool help system I am not sure if the docs would have to list all the parameters. The docs could be shortened to a more verbose explanation of the function's purpose and to examples. As a rescue net if your on-site help is not enough. For these pages your proposed hierarchy is great: docs docs.handbook docs.handbook.functions docs.handbook.functions.breadcrumb Thoughts? -- You received this message because you are subscribed to the Google Groups "BoltWire" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/boltwire?hl=en.
