At 21:20 -0500 11/14/08, Matt Aimonetti wrote:
> Any suggestions about how to implement your recommendations?
Well, I'd like to resolve the specifics of how each mashup should
look and act before getting too deeply into implementation, but
here are some strawman proposals:
> API/wiki mashup
>
> I'd like to be able to comment on the API pages as I read them
> (eg, ask questions, make suggestions, etc). If the online API
> docs had MediaWiki-like capabilities (eg, discussion pages,
> editable content), we might well get a lot more feedback...
There are a couple of approaches to this, depending on whether we
want the API app or the wiki to be "in front", etc. For example:
* Auto-populate the wiki with a page for each item (eg, class,
method) in the API. The page would dynamically include
API information, nestled in among comments, questions, etc.
For convenience, add links from the API to the corresponding
wiki page(s) and vice-versa.
I haven't looked closely at the wiki being used, but TWiki
and MediaWiki are quite capable of supporting this sort of
thing, along with handling metadata, etc. MediaWiki scales
better, but it's easier to push content into TWiki...
* Add some sort of blog/wiki/??? slice to the API app.
> code/RDoc mashup
>
> Consider the @public tag. Although it is visible to RDoc, it
> is not (as in a Python docstring) visible to the program. I'd
> like to have a low-impact way to add metadata that can be used
> both in the documentation system and in the running program.
Again, there are a couple of approaches:
* If we want the metadata to stay in the comments, we can write
a method to extract the metadata for a specified object at
run time. This doesn't have to be particularly efficient, as
there will probably be relatively little call for it (:-).
* If we're willing to burden the code with declarations, we can
stash all sorts of information in a metadata object. This is
not going to cause all that much performance loss, given that
each declaration only gets executed once. The other issue is
that we'd need to harvest the declarations for the doc system.
Regardless of the approach taken, I'd like to see the metadata use
an extensible, self-documenting format such as JSON or YAML, so I
could add my own tags (etc) without asking anyone's permission.
-r
--
http://www.cfcl.com/rdm Rich Morin
http://www.cfcl.com/rdm/resume [EMAIL PROTECTED]
http://www.cfcl.com/rdm/weblog +1 650-873-7841
Technical editing and writing, programming, and web development
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"merb" 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/merb?hl=en
-~----------~----~----~----~------~----~------~--~---
