On Mon, Mar 22, 2010 at 4:09 PM, The Editor <[email protected]> wrote: > On Mon, Mar 22, 2010 at 10:22 AM, Markus Weimar > <[email protected]> wrote: >> >> 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. > > I'd like to see the more expanded docs put on BoltWire.com not in the > code. I tried to add a single line of "brief" notes to each function > only grudgingly, though it did make a cool help system possible.
I think we can find a common denominator that brings advantages from both views. When I first saw the help system I was disappointed. I expected something like a formulary but what I found was a source code browser. I said to myself this must be intended to be used when you have no access to the code and you need to look something up. This is okay then but of little interest to me as I have access to the code and a text editor. Then I saw that more or less hidden page with the title "Editing Notes". A markup table with preview only two clicks away! Very, very nice and much potential. Proposal. Forget what I said about code documentation and stick with one line. But what do you think about changing site.help as follows. Partition the page in two sections: quick reference and code browser. The code browser stays as it is. The quick reference would be that API-like structure we have been talking about. Markups are there. Why not add the same for variables, functions, conditions and commands? No verbose documentation, just a quick reference list. The extended docs will be on BoltWire.com. And as the quick reference would be part of BoltWire, it would automatically be on BoltWire.com, too. I would love this. And I could much better use BoltWire when sitting in the sun without net access. It would make the system more complete and less dependent on the website. > I'm > not enthusiastic about changing the internal code docs--other than > specific text replacements were suggested of course. Things I probably > won't change: > > * More than a single line of docs per function > * Dropping the all caps. > > In my view the latter makes it easier to distinguish between code and > docs, and are easier for me to ignore! Not to mention the time > involved in redoing every single one... As said above, forget about the extended code docs. With the above solution I would probably never have to look at these caps again. And you are the one who spends the time coding. Just as a note. I use a text editor where I have a function list to jump to each function and comments are grayed out. This way they never disturb me. When using an IDE multi-line comments are collapsed and also no more disturbing as a single grayed line. >> 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. > > This seems adequate to me for it's purpose. The help system is just > brief hints for advanced users. I'm assuming people will have to test > it out a bit to fully grasp it all. I'd like to see much more thorough > online docs--not try to move those potential online docs into the > code. > >> For these pages your proposed hierarchy is great: >> docs >> docs.handbook >> docs.handbook.functions >> docs.handbook.functions.breadcrumb > > I'll see if I can find some time to move over all the pages, but not > sure when I can do it. To be honest, I'd be tempted to just start over > and delete the entire docs.barn hierarchy. To be honest, I thought I > had already... Do so. From scratch often gives better results. And yes, you have been talking about deleting these pages for a year at least. ;) I'll be happy to help as much as I can. -- 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.
