Folks, When documenting code perhaps mouse over and alt text could be used along with highlighting so an optional items being bold nd green could support screen readers and the color blind with mouse over text? We do have rich environment available after all. I am sure there are standards we can follow.
Tones On Friday, 28 May 2021 at 03:47:37 UTC+10 Mohammad wrote: > > > > Best wishes > Mohammad > > > On Thu, May 27, 2021 at 4:28 PM Stobot <sto...@gmail.com> wrote: > >> 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? >> >> > Sure! I help with PRs! No worries on this and if you like I can prepare a > short slideshow to teach you how to do so! I am sure Saq and Jeremy will be > there to answer our questions and give advice on how to do this! > > > >> 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 tiddlywiki+...@googlegroups.com. >> > To view this discussion on the web visit >> https://groups.google.com/d/msgid/tiddlywiki/9936c0a8-f090-4973-bdc6-d4551b5e5879n%40googlegroups.com >> >> <https://groups.google.com/d/msgid/tiddlywiki/9936c0a8-f090-4973-bdc6-d4551b5e5879n%40googlegroups.com?utm_medium=email&utm_source=footer> >> . >> > -- 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 tiddlywiki+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/0311f57a-f71b-4ec4-a01d-da842a2c67cen%40googlegroups.com.
