Reader-driven documentation development

Community Projects Documentation
#30

See my last reply before this one. The idea to include links to old discussions is only for convenience, a luxury.

I can envision automated solutions (either put on the tiddlywiki.com side or on the talk.tiddlywiki side) but I think it would be overkill. How often do you wish you had access to outdated docs on tiddlywiki.com ??? And even if you do wish this, is it really necessary with direct links if you could just use the search engine?

This detail is a side track. What do you think of the workflow I describe?

#31

The problem is, that we have a system that is designed to deal with exactly those problems.

General discussions about docs can happen here.

But as soon as something is pushed using 7 Steps to Improve the TiddlyWiki Documentation the discussion about the single fix has to be at github.

We (the devs) need it there. … Linking back from a pull request with eg: 2 or 3 minor changes, to a TiddlyTalk discussion with 50 or more posts, is completely unusable.

There is not enough time to read 50 posts, just to find the 2 that are valid for the proposed change.

#32

I don’t understand what you’re saying. Maybe there’s some premise one of us has misinterpreted:

My interpretation is that on tiddlywiki.com there should be a feature to show an active discussion about the tiddler. This discussion should take place here on talk. A main point is to co-develop the tiddler but it is not a PR. Anyone can start this discussion (if it is not already started) by – as per my proposal – clicking a link in the tiddler which triggers some magic to create a new thread here.

To avoid outdated such discussion threads, I am suggesting that the thread URL makes use of the modified field, which is obviously also accessible on tiddlywiki.com so it is simple to automatically show the correct and latest thread there.

To make the actual PR is another matter. Just like currently, whenever someone feels the urge to make the PR then this person can simply copy the resulting text from here and make a PR using your 7 steps or however he wants.

#33

As I wrote here: Reader-driven documentation development - #23 by pmario There is a high probability that it is possible to create “dynamic links” as you describe. …

Someone could test the functionality described at: How to create a new topic link with pre-filled information - faq - Discourse Meta … If it does work to create a “dynamic” thread, that is linked to a specific tiddler with a specific “modified” date. … I don’t know.

1 Like
#34

Would it be possible that the GitHub PR merge process itself automatically generates a new message in the TTW thread ?
If so, a reader coming back to the thread later could see that the object of the discussion has been merged in the documentation, maybe with a link to the PR.

#35

7 posts were split to a new topic: Misleading attribution

#36

GitHub has a very powerful notification mechanism. But I’m not sure, where the possibilities for open source accounts end. … but probably yes

Discourse also has a powerful mechanisms to receive new content. Also a yes here.

Techy stuff
Discourse docs
GitHub docs

#37

It might be possible to customize Discourse comment threads to work inside TWs dynamic nature.

I know it will work out of the box on the static docs.

#44

Ok. Tested. You can play with it (for awhile) here. Only changed the configuration banner. I’ll probably delete the example in a few days.

The title has to be at least 15 characters, which is why there is some otherwise unnecessary text in the title. The main problem is that Discourse doesn’t recognize duplicates. So it won’t join an already existing thread. I guess moderators could just append duplicates as they show up.

No, I haven’t done anything with the modification date. But I guess it would be easy enough to append it to the title, making the distinction more clear. But this should give an idea if the basic idea is worth pursuing with a PR, etc.

#45

Ha! Well done! That was fun. But can the tiddler text come along?

#46

ALL of the text? Have you seen “HelloThere?”

In theory, as much of the text could come along as the internet allows encoded in a url string. Have to go look that up.

#47

Well, isn’t the whole point to post a copy of the full text as a basis for the discussion and joint development of it? (Why else?)

#48

Well, that length is actually quite long, at least if itty bitty is any indication! (Note the url, ~4000 characters)

#49

It’s to start a discussion – not necessarily re-invent the tiddler.

It turns out that the answer is browser-dependent. IE has a limit around 2000 characters. Android around 8000. But Chrome allows 32k characters and FF 64k characters.

So, we could impose an arbitrary limit, or limits based on what os/browser you’re using. Or just pretend that everyone’s using FF.

I’m not sure at the moment if carriage returns can be encoded, so that may be a problem too.

#50

Actually, I guess the biggest tiddler on tiddlywiki.com sets the needed max limit :slight_smile:

Right, if we’re unlucky we hit the same problems as with the Share plugin which did something similar.

#51

So another approach might be if tiddlywiki.com could know if the URL already exists or not. If it does already exist, then tiddlywiki.com would only show a regular external link to it and only if it does not exist would the link be the magic link.

So I guess the question is if tiddlywiki.com could send a ping to see if it exists?

#52

I don’t think discourse will respond to a ping at a particular thread. That is, it’s only going to respond to the domain.

I think the easiest solution is to occasionally merge threads that are on the same topic. I’m thinking this will be a rarity.

I’ve added code so that it will grab all the text in the body and submit it. I’ve ignored size limitations for the moment. There are certain characters that require special handling, and I don’t know if I’ve managed to account for all of them. But it works for “HelloThere” and “Getting Started”.

#53

Merging threads manually… rarity - OK, I guess the only way to know is to test.

Great! I tried your mirror site but the resulting editor here on talk looked like before, i.e a proper topic heading but no text. Where can I try it with the text? :smiley:

#54

There’s a possibility that I didn’t hit “save”. There’s also the possibility that you didn’t reload. Yeah, let’s go with that one :wink: . Be sure to clear out your existing talk tab in case your browser is smart enough to navigate back to it instead of loading a new site.

You’ve replied to @twMat 3 times, did you know you could send them a personal message instead?

Edit: I’ve gotten rid of the preamble text and instead appended the date in plain numeric format. That should make it clear which version of tiddler we’re on, and also solve the 15 character problem. Keep in mind that there might be some tiddlers without modification datestamps.

#55

LOL! :grinning_face_with_smiling_eyes:

I tested a few and it works quite well. I did hit the limit with the tiddler Code Blocks in WikiText but that is understandable.

…

As for checking broken (same as dead?) links a google search implies there may be js to do this. I’m too tired to read closer right now tho.