Plain English in the documentation

Community Projects Documentation
#1

My overwhelming impression, returning to TW, is that you need another reset. It’s technobabble is unfriendly to the point of rendering it unusable to a newbie. Looking for examples came up with the markdownguide.org site as an example of how it should be done, rather than the mess TW5 has.

I think you need four major documents, Intro, Structure, Grammar and CheatSheet. Get rid of the spin, cut to the chase.

Intro might take a shopping list as an example, developing it into all the basics. Structure should be a full top-down definition, Grammar, a full bottom-up definition. Have a clear demarkation, make html a boundary marker, predefined as “as defined in …” - others may be necessary.

Where does Structure start? I’d suggest at file level. Hyper-Structures could be Taxonomy level O.
Major taxonomy:
Top level 1. Imported 2. Core 3. User Coding and API
Structure 1.1 Importing tiddlers 1.2 Importing macros 1.3…
Structure 2.1 Display environment as a data structure
Structure 2.2 Full tiddler definition as a data structure, including additional fields etc,
Structure 2.3 All instances of TiddlyMarkup grouped by Lists, Tables, Formatting…
Structure 2.4 Built-in macros and other coding
Structure 3.1 Full Core System Code definition
Structure 3.2 User coding - overwrites
Structure 3.3 Imported coding - specification of documentation for offered extensions
Structure 3.4 User coding - new objects
Structure 3.5 Full API

Grammar and Cheatsheet. Essentially the same, with the Cheatsheet omitting the full definition, and possibly minor elements.
Grammar 1 Data structures
Grammar 2 Major classes of markup
Grammar 2.n Full definition of Subclasses, grouped
Grammar 3. Add-ons and extensions, a dynamic collection likewise grouped.

Annexes. Because Structure and Grammar are coming at the same onjects from opposite directions, it’s probably better to abstract them here. Treat each element as a full object definition, including creation, all inheritances, full structure and functions, including storage, and destruction. A list of referencing calls might also be useful. This may be Annexed, to allow referencing from several points.
Annexes 1. A simple grid of referencing from the above, with the taxonomies as each axis.

1 Like
#2

G’day,

I’d suggest the goodness that is Grok TiddlyWiki. It it very well written and organized. Way more human-friendly.

Total aside: Maintaining TiddlyWiki documentation at TiddlyWiki.com involves a process that I find complicated and cumbersome, so in my mind doesn’t really lend itself very well to easy/quick improvements. (I love working on documentation, but I need a particular kind of process; besides, I’ve got way too interesting things to do in my non-paid-time.)

Not too many folk have a love affair with documentation, and it is a hard thing to get juuuust right when relying on folk throwing in their free time into the writing and the process of getting documentation updated.

#3

Hell, how can I put this in a way you’ll understand. Heinlein was deleted in 2000, after his work was utterly perverted. Nobody under 30 will know what grok means, and of those over, 2% have neurodiverse minds capable of actually applying it. I’m one, I delivered Carl’s skillset for real, in the European Common Foreign and Security policy team, the extra edge which won the 2012 Nobel Peace Prize. Imran Khan just gave the solution I found for Pakistan long years ago to Putin, who had to think about it. He’s now at the peace table himself.
The Grok book tells me the old system of installing extensions remains the same. But where are they? Github? I just had their DungeonMaster breach my privacy and try dictating my security protocols. Big mistake, given mine were set by some of the heaviest around, for very good reason. And that’s before you try translating their file alchemy into anything my mainstream Chrome can cope with. Plain English.
Now, since I last looked, Eric Shulman has resurfaced. There is yet hope. He talks reliable sense. But [all[current]get[fieldName]enlist-input:raw[]] [] as a way to catenate two strings (a snippet from the GoogleGroups update 17 Feb) just has me befuddled.

#4

First, as a lead up to conversation about a few TiddlyWiki concepts, concatenating two strings:

the filter:
[[string1]] [[string2]] +[join[, ]]

to process and display the results of that filter:
{{{ [[string1]] [[string2]] +[join[, ]] }}}

to display the results of that filter without the results being links:
<$text text={{{ [[string1]] [[string2]] +[join[, ]] }}} />

That aside, what you explained was fun to read, but I won’t pretend I understood what you were trying to say. So I’ll withdraw and leave it for somebody else who does understand to have the conversation with you.

Cheers and best regards !

2 Likes
#5

TW is way more complex and powerful than a mere markup language and hence the documentation is a totally different beast. But, yes, the current documentation is more of a technical dictionary and I agree we would all benefit from additional approaches.

I like how you come with an actual proposed draft for a structure. If that structure is good enough, or if someone else with the chops can provide a better structure, it could be a collaborative project to “fill in” the actual text …buuut, unfortunately we don’t quite have a collaboration platform that most people can use. Most people here are not software developers. Or, viewed in another way; those who can use the collaborative platform we have, i.e github, are probably too few to actually get a momentum going for authoring something as ambitious as you ask for.

That was recently solved, to some extent: Links. But a lot of plugins (including, still, mostly of my own) are found wherever individuals choose to publish them. We don’t have the infrastructure nor economic incentives that many other open source communities have, and arguably not the same culture either.

#6

Fyi. There is a documentation Forum in discourse.

I will move this topic there soon if the Author does not.

There has already being a proposed structure in the past. Not withstanding valid Critisisiums may I suggest

anyone wishing to say something about the documentation do a little documentation and there will remain little left to document.

5 Likes
Railway Syntax Format
Railway Syntax Format
#7

I’ve been working in the general direction @TW_Tones suggests, roll-my-own and make it available. I’ve looked at @Charlie_Veniot’s book, but find it enmired in the existing problem.
My first issue thereafter was to find a tool to handle the documentation, and I finally located my memory of Railroad Syntax Documentation, tackled Tad Atkins’ site, only to find I came straight back to my starting point, the Railway add-in to TW! We have the tool, let’s use it.
So let’s adjourn this to my second thread Railroad Syntax Format. In that, I’ll also raise the question of where to place that, how to beta-test it (given I can be high-level geek), and possibly make it a multi-user Working Group operation.

@TW_Tones
I entirely concur with your thinking, but I’m afraid I won’t be able to follow to Discourse, for two reasons: I’m Neurodivergent, which makes SM a Sado-Masochistic experience rather than Social Media, and I’m security-vetted after that condition placed me very high in the diplomatic service: my exact condition is hyperperception, akin to ESP. My mind is an excellent pattern-searcher in data fields far larger than most can cope with, although possibly not in this community. Anyway, the security community hate Social Media with a will, because it’s a front-end to character profiling, in turn used by our less-friendly cousins of the Evil Empire to push our psychological buttons. Not fabulation, I had a work-up with a Special Forces shrink a year back. Don’t ask.
You’re welcome to shadow this to Discourse, of course, but you won’t find me there, obviously.

@twMat What you’re picking up is that I can be like Stephen Hawkins’ A Brief History of Time, I have to constantly fight going A-E-I-O-U when most folk need A-B-C-D… It’s complicated by networked thinking, which allows totally contradictory concepts to exist simultaneously! Language is linear, my thinking isn’t, so of course TW is an essential tool for me.

@Charlie_Veniot Thanks, that was just an example of a wider issue, so let’s adjourn to the Railway Syntax post. We need to open this out, not close it down to excessive specificity - I’m a pathfinder by nature, in passing, and may need to leave something like a Working Group I can beta-test. In fact, you’re inability to follow is a practical worked example of what I was on about in my second posting, few people know or fully comprehend the “Grok” concept, which is another angle on transcendence. That book, now I’ve worked through it on a first pass, is not that, but rather a deep dive into a specific approach: in short, it lacks the ontological approach. This comes from the techie team who recoded TW: it’s time to get your heads out of the code and look around.

As I say, let’s shift this to the other posting.

1 Like