Thanks everyone for the feedback!
@Soren
- Good point about the formatting on the values in the Default section,
I'll try parentheses.
- I ''strongly'' agree that every attribute should have an example. I
might have to put that as a secondary effort though to make sure I finish
this.
- Good reminder again on color-blindness. I did end up going with the
bold / italic setup so I think I'll stick with that unless I hear of
something better
- I like the note about doing source="MyImageTiddler" rather than just
source as I have it. I actually did that originally, but after realizing
how many attributes some of these things have, I counter-balanced against
the length of the syntax mockup. I think you're probably right anyways, and
I think your point about a maintained table of example values per type
makes sense - good idea. But take a look at something like <$edit-text/>
which has 20 attributes. At a certain length, I worry we would lose people,
or you then get into a kind of stepped layout where each attribute gets a
newline?
- I agree on the order, I did put all the required ones first, and then
took some liberty on ones I thought were most common, but alphabetical
probably makes more sense. Counter to that might be to bundle (sort
together) the ones that go together.
- Your last point on multiple required attributes is similar to where I
was thinking about too. For reference, using your example -
<$action-setfield>
- Your suggestion: <$action-setfield $tiddler="tid" ($field="field" |
$index = "index" | *text* field) $value="value" /> - what does the
*text* field part mean?
- I was thinking about the combinations that were valid could all be
spelled out. For example either tiddler or field are fine, and if you use
index you need tiddler too.
- So maybe: <$action-setfield ( $tiddler | $field | $tiddler + $field
| $tiddler + $index ) $value /> - though again that gets long if there
are
lots of options like this.
@Tones
- I commented on your other thread on CSS - I agree that's an
opportunity for a little more to be added to the documentation also
- I also like the "copy to clipboard" piece. I saw that in many of the
examples and will try to implement it by reverse-engineering the core macro
that does it.
- You bring up a lot of other things that while valid, would be massive
scope creep on an already large effort, but I'm happy to pencil in for
future "phases"
- Multiple versions of common widgets, like the filtered transclusion
example, good point.
- Documentation of macros & <$macrocall/> syntax
- Examples should all work on TiddlyWiki.com - totally agree. I think
the whole "recipe book" idea as base data (as is used for some of the
filter stuff is a good starting point myself)
- Test-data / plugins: Good ideas too, as above, I think a small
internal dataset like recipes / ingredients etc. are perfect for starting
though
- Send-message vs. action widgets (paraphrasing) also valid thing to
further describe
- Whole learning environment: My personal opinion based on other
languages is that I like the core to support main syntax and examples,
and
leave external sources for more guided training (such as Soren's Grok
book
and videos)
@Mohammad
- I'll take a look at Shiraz and the Alert Macro as you suggest.
- The general flow you illustrate sounds good to me, and I think is
similar to what TiddlyWiki has, but with just a few missing pieces.
- Agree with you and Soren on bold / italic vs. colors, good point
- I agree (mostly) on the consistent outline (constant number of
sections), though to keep the scope small, thought would be to split the
effort into phases to increase the liklihood of it getting finished.
- Syntax and Attributes table would be phase I
- Examples and other cleanup could be phase II etc.
- I agree on referring to the other languages for inspiration. A saying
I'll sometimes use is that "sometimes consistency is more important than
accuracy" which sounds counter-intuitive, but if the end result is
learning, absorbing material is job 1
@TiddlyTweeter
- I understood where you were going with your comments in the other
thread. I think there is definitely a "too far" area, and having much
deeper learning can be better handled in other places, with other mediums
even
- I agree on the scope, and will definitely not make everyone happy with
what I plan on doing, but I think it most prudent to break the effort into
phases as mentioned above. If I / we don't do this, the chance of giving up
before completion is high
- Just adding the Syntax section and tweaking the Attribution section
is what I'm considering phase I, Examples maybe phase II, and then other
areas besides widgets (filter operators, macros, CSS, SVG etc. could come
later)
@Álvaro
- That point is really valid and Soren agrees. As I mentioned to him I
only worry about the length, but you additionally make the point that
without it, people could falsely assume that you can omit the parameter
name and have it work in a position-based way, which you can't. So maybe
I'll have to relent there.
- I'm not clear on your second point. I will say that the mockup does in
fact use a macro as a template as you describe if you scroll down a bit, so
all of the parameter information is in fields and the syntax bit is
generated centrally so it can be tweaked. If you mean something else, maybe
elaborate a bit more?
All, thank you again for the feedback, I'll take another look tonight and
incorporate what I can from the above. As mentioned I'll intend to do this
in phases and at least make it through Phase I. My day-job is quite
strenuous right now (normally 12-hours/day X 5 days and then maybe 4
hours/day on the weekend), so this will go slowly. For those curious, I run
a team of project managers, so that's where my background of project
managent, scope, requirements etc. comes from.
Parting questions for now:
- Is there a better way to get per-tiddler commentary? I think I
mentioned doing the Disqus thing, is anyone interested in participating
that way? I wish there was a multi-user environment available for this kind
of thing.
- Who has to approve this for it to get implemnted? I know @Mohammad
offered to turn the result of this into a pull-request. I still worry we
might get to the end of this whole effort and the right person doesn't say
yes?
On Thursday, May 27, 2021 at 2:56:35 AM UTC-4 TiddlyTweeter wrote:
> Mohammad wrote:
>
>> I have attached a sample doc from Excel
>>
>> The same sequence: purpose, syntax, arguments (in/out parameters),
>> remarks, examples
>>
>
> [image: Screenshot 2021-05-27 085252.jpg]
>
> Ha. Very good example!
>
> And, YES. We are all Sinners, and especially Microsoft :-)
>
> TT
>
--
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 view this discussion on the web visit
https://groups.google.com/d/msgid/tiddlywiki/9936c0a8-f090-4973-bdc6-d4551b5e5879n%40googlegroups.com.
