Other sorts of Documentation

#1

I was responding to the discussion when I realized I’d wandered way off-topic, onto one that I keep coming back to, and decided to raise it on its own:

I absolutely want to find good ways to contribute to the documentation. I’ve thought about it a great deal over the ten or so months I’ve been active here, and I’m increasingly convinced that what I want to do is to start my own documentation wiki, with the goal of eventually try to fold it into the core, but not to attempt that until it has worked itself out into a reasonably useful set on its own.

This is not to say that I wouldn’t contribute to enhancements for the current documentation; I absolutely want to. But I take seriously the Divio documentation system, which I explain in the documentation template I use for new docs projects. This splits documentation into four categories, Tutorials, How-to Guides, References, and Explanations.

image
image1516×853 134 KB

The main site serves wonderfully as a source of Reference documentation; where it’s lacking, I think it can be easy to fix. There are a large number of How-to Guides, although I think there’s room for many more. (For the motivating thread, I could easily imagine a “How to make a custom sortable list of tiddlers” as a useful topic.) But I think we’re lacking a lot in the Tutorials and Explanation areas. While I love *The Philosophy of Tiddlers" Explanation, I think it could be expanded a lot. There are many more topics I’d love to see. And there is certainly little Tutorial-level material directly in the main site. While things like Grok Tiddlywiki help fill that gap; its single sustained example is great for a complete read-through but not as a likely source for learning specific high-level topics, on my own schedule and order. Think “Using Drag-and-drop” as a reasonable-sized Tutorial.

Twice before I started on this, only to abandon it quickly. I haven’t been ready to spend any real time with it.

I’m still not ready.

But I think I need to start doing it anyway. I’m afraid I’m starting to get the hang of too many parts of TW, and the learning frustrations are diminishing. That means I’m starting to lose the beginner focus that should inform much non-Reference documentation.

So expect an announcement in the next few weeks. But before that, I would love to hear objections, corrections, suggestions, or any other feedback.

11 Likes
EventCatcher with drag-and-drop
#2

Yes Please
!!!

It sounds like you are at the perfect escarpment to tackle this now…

It’s even hard, in my experience, to write :writing_hand: a proposal raisonné outline, like you just did

I hope I can help

Necessity being the mother of invention
Frustration often an alt-fuel

1 Like
#3

I want to double-heart this post.

I’ve recently been introducing TiddlyWiki to an undergraduate research student, and wish that I could offer a documentation resource that would be less … bumpy (?) than going to tiddlywiki.com as a resource. (I did include a link to the new superb-for-beginners “tour” interface, despite the fact that searching for “help” there — as suggested by the tour itself — currently yields a cringeworthy radio silence… hopefully something that will be remedied!)

In my own experience, tiddlywiki.com is fantastic for the reference situation where, say, I realize I want to review how :map vs subfilter vs :filter each work, and exactly how the syntax goes for each. But really frustrating if I’m not sure whether or how something can be done, and I’m lacking any awareness of the terms I would need in order to find out.

Something like groktiddlywiki is amazing for someone who’s “all in” with becoming a decently well-rounded user, and fits in your “tutorials” quadrant.

But when tiddlywiki is being harnessed by someone whose main interest is getting on with a project that is not tiddlywiki, some kind of how-to guide — perhaps combined with a minimal amount of explanation to consolidate the understanding in non-geeky terms — would be ideal!

5 Likes
#4

Just so you know how others approached this learing curve, from the early days of tiddllywiki 5.1.x I took a copy of tiddlywiki.com localy and added my own notes to it for a couple of years, I built up my own notes with a ver to later publishing or contributing to the documentation. I can see how my past self thought about things.

Since then I maintain tiddlywiki’s for self documentation and as a resource to help others, and I gradualy contribute to the documentation. My current TiddlyWiki dedicated wikis are;

  • Collected Plugin repositiry with most plugins disabled
  • A collection of references and code patterns
  • A References wiki for finding images, icons and other commonly used materials
  • A more recent copy of tiddlywiki.com with a help tiddler against key document tiddlers including click to copy widget or macro calls in their different forms.

I have other resources but the rate of change has being quite high of later so they need extending but I need to know the new features well to document them, so first I am developing a deeper understanding, and hope I remember my newby perspective when I come to publishing.

Perhaps a searchable blog would be a good way to document newby expierences so you can go back and additional notes once new ways to look at it come to mind.

If you want to construct tutorials do a search because there are some wonderful tools to support user ionteraction including @jeremyruston recent publication, just can’t find it now.

  • Also the innerwiki plugin allows you to spawn wikis from inside another and people could freely experiment without harming the parent wiki.
2 Likes
#5

Scott,

I am glad you are trying to get to this. Do it before you get too good at TiddlyWiki, so that you keep at a level that helps people tthat need it the most. There is a lot of good entry level stuff, some of which I have done. But the mid-level instructions are where help is needed the most. All of the new stuff in the last couple of versions have left me behind in the dust.

Oh and if there is anything in Documenting TW — a non-linear personal web notebook that you find helpful, please feel free to use it, adapt it or whatever. That is a document that I update periodically for my own sake, for quick reference, but I always hope it is handy. It is somewhere between tutorials and how to guides.

4 Likes
#6

Thanks for the encouragement, everyone!

Me too. The thought is that this would be a community effort, but with one editorial voice in control – mine until I abdicate! I don’t have the exact mechanism yet, but I’ll figure it out, and don’t expect it to be too hard.

I’m hoping you’ll be willing to help with that. I do tend toward geeky terms, and need someone to slap me down if it gets out of hand!

I’ve been doing some of that self-documentation, but not nearly enough. But for now, I specifically don’t want to start from the main site. I want to think about it from the start, and try to create a wiki that is dedicated to nothing but TW documentation. If it works, and if it builds into a useful tool, it’s worth seeing if it can fit back into the main site. I hope it would, but would not be surprised if it simply won’t work. If so, a separate stand-alone documentation site would not bother me overmuch.

I’m probably going to treat it more like my other documentation projects, with constant creation of links to non-existent pages, and a tracker to show what is considered complete, what it in progress, what still needs to be started. My documentation skeleton already has that feature.

Thank you!!! I was searching for that term, and could not find it. I was sure I’d seen the notion in discussions, but I tried “subwiki” and “nested wiki” and a number of other search terms and could not find that. I agree that this could be helpful. I haven’t tried it yet, so we’ll see. But I’m thinking that the documentation site won’t ever use its own content as examples; that too easily can lead to confusion… Instead I would like to have a handful of sample wikis (if TW can handle that many of them), with enough variety between them to allow them to cover a great many different styles of TW.

There’s all sorts of great stuff out there. I’ve seen much of it, and I will ask for help identifying more. I’ve learned from many of these sites, including ones by you, @pmario, @telumire, @saqimtiaz, @EricShulman. And I’ve learned even more in these forums, again from many of the same people, as well as all the people on this thread, especially @TW_Tones.

So my biggest concern on even contemplating embarking on this project is this:

Standards

That seems extremely likely. But maybe I can manage to avoid it.

Oh yes, I’ve been there at least twenty-five times as I try to learn new things.

The biggest problem is not in finding content; its one of organizing it, and consolidating it into something useful.

While I would hope to solve that, it’s going to be a big problem, given the breadth of TW. The list of “Concepts” on the main site, without expansion, has 42 entries. And that’s just one of the fifteen topics under Reference, which itself is one of a dozen main entries in the TOC, most of which contain a great deal of documentation.

In fact, this I think is the second most-likely reason that this project might fail: there’s just too much, and trying to improve on what we already have is a Herculean task. (The first most-likely reason is that I decide to scamper off with my tail between my legs when I realize just how much I’ve bit off.)

2 Likes
#7

Perhaps putting some of the simpler examples in an iframe would help — where the iframe content can also be “popped out” to load directly (I’m thinking of tiddlyhost as ideal for this), but people could peek at a technique or concept being illustrated without having to navigate to another page.

1 Like
#8

Sorry, I meant this in the innerwikis that Tones mentioned. I would like to have this self-contained. I don’t know if that is done with iframes or something more subtle, but the idea would be that this is something the user can see from the main page, but which is not the actual main page itself. I’m hoping that innerwikis can help with this. But I won’t have time to even look at them until Wednesday at the earliest.

#9

Asa to most core plugins there is a tiddlywiki with it installed https://tiddlywiki.com/plugins/tiddlywiki/innerwiki/ at the top the example tiddler it says Renders as this is actually a working innerwiki.

  • As I understand it, the initial purpose for this was to allow you to “overwrite” it with svg see down the page. Then you can snap shot this to file from the command line to prepare documentation, but his recent share is superior.
  • I like the inner wiki because you could use it to generate new wikis using a subset of what is in the parent wiki, and you can save that to file. Dial a wiki.

Post script
Both with iframe and innerwikis you can drag and drop between them.

1 Like
#10

image

xkcd ^° wise genius on point :point_up:

Recursive brilliant nested folding nature of TW is also its own worst enemy when it comes to finding, understanding, explaining, showing and documenting it

Fresh different community effort is needed
Format, medium & design approach

/// I’ll try to suggest my thoughts soon

Thanks to everyone here ongoing who tackles this

ChatGPT has something to help in it’s pedagogical structure

Best of TikTok (now YT also) mini tutorials and pithy introductions> highlights video shorts _ as structured, and/or grown series

Rust language error messages are brilliant successful for many people

I’d be open to trying to setup OBS Studio and recording sessions, to help flush out video Q&A how to
Intro
Show me
Expert :: student
Etc
Then re edit repurpose

Invite innocent interested people: students authors teachers, who want to use TW — for building an illustrated book, or courseware, or other resource resource = non experts
Non TW addicts or adepts into the newdoc project.

// I consider myself in this category for ever with TW
So I volunteer as a candidate TF frustratee(?)

Onwards

1 Like
#11

Those are excellent ideas thank you @Scott_Sauyet, and would be welcome improvements.

2 Likes
#12

For this peculiar problem, I just checked in tiddlywiki.com and html comments are listed in search results.
So maybe it would be useful to add aliases, related terms and concepts inside html comments in documentation tiddlers?

image
image1192×499 76.5 KB

Fred

#13

Oh, cool. I had no idea, but it makes sense. Why try to parse them out in the search?

That sounds like a very good idea!