I'm trying to do this same thing at tw-for-bunnies, but I'm approaching it
from the other end. Here are my observations (some of which I'm thinking of
on the fly)
# As a user I need to understand the structure of widgets and macros so I
can use them myself
#* The structure of widgets and macros documentation seems to be as
follows
#** Widget or macro name
#** Widget or macro parameters
#** Widget or macro description
#** Widget or macro examples
#** Widget or macro called_variables
#** Widget or macro usage_by_other_widgets_macros_and_tiddlers
# As a developer I need to know if the requirement for documentation means
that I need to change my coding style so I can adopt that standard once and
then focus on development
#* Jeremy has adopted the following standards
#** <!-- html commenting his code -->
#** Code comment includes
#*** purpose
#** Separate doc tiddler to document the macro or widget
#** doc tiddler text field contains
#*** Widget or macro name
#*** Widget or macro parameters
#*** Widget or macro description
#*** [[Link to]] Widget or macro examples
#** The code itself contains
#*** Widget or macro called_variables
# As a documentation developer I need widgets and macros coded in a
standard format so I can extract the documentation rather than documenting
each widget or macro individually
It would be helpful if we could decide on a standard way to approach this
and then Jeremy could publish that standard as part of the core
It seems we have much of a standard format defined for us. Once a standard
is established, writing tiddlers and macros to build a documentation
management interface would be fairly simple.
Next step would be figuring out a pipeline to feed community developed
documentation and examples into the core. (This is the internet so the
horde will skip and mix steps but . . .) Something like
# Anyone develops things on their own
# Collaborators post code to a "test it out and provide comments here"
website such as twederation
# Moderators browse the twederation to identify "good stuff" and
provide professional polish
# Contributors Post polished tiddlers to github
# Jeremy says "Hey everyone needs to know this" and puts it in
the core docs
I'm thinking of implementing the following in my documentation standard.
# Segregating each widget or macro into a separate tiddler
# Use the following fields in the macro or widget tiddler itself to outline
the macro usage
#* name = widget or macro name
#* parameters = List of parameter names
#* description = Long description
#* caption = Short description
#* tags = If contains "$:/tags/macro" this is a macro
#* type = if application/javascript this is a widget
# Use the following in each macro or widget example tiddler
#* example-for = List of macros or tiddlers that this example documents
Why I haven't adopted this yet
# During development of macros, I find that writing a whole bunch of macros
together in one tiddler is the most efficient way to develop for a
particular use-case since the macros tend to be dependent on each other
What I'm using instead
# Each use case is a separate tiddler with a whole bunch of macro
definitions
# If there is only one macro in the tiddler, I add the following text and
make sure the display is illustrative
! macro name
* `<macrocall $name="macro-name" parameter1="example" parameter2="example"
/>`
* <macrocall $name="macro-name" parameter1="example" parameter2="example" />
# If there are many macros in the one tiddler, I add text after the
definitions to create a table, one row per macro with the illustration
--
You received this message because you are subscribed to the Google Groups
"TiddlyWiki" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at https://groups.google.com/group/tiddlywiki.
To view this discussion on the web visit
https://groups.google.com/d/msgid/tiddlywiki/4522703a-a0fb-4c50-ab17-a872afb3cfaa%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
