Reader-driven documentation development

Community Projects Documentation
#26

Good point. If (if!) threads could be automatically generated on talk, then an accepted PR of a tiddler (i.e in github) could have as a consequence that a new discussion thread will be created, to start blank. I.e the generated URL’s could for example be:

https://talk.tiddlywiki.org/<modified-date>/<tiddlername>

I.e the modified date serves as a version number. So the discussion thread automatically shown on tiddlywiki.com relies on this url, so the shown discussion is always for the latest version of the tiddler.

Since the content of this first post is editable for those who have the right to do so, it is easy enough to manually add links to previous discussions if the need arises. Do consider that we’re mostly talking about docs, in contrast to real code dev which happens on github. So as long as we have the “EDIT THIS POST” feature here, it is simple to dig up and link to any previous threads in the rare case that they are still interesting!

Here’s a full hypothetical workflow:

  1. In a tiddler on tiddlywiki.com there is a “Discussion” button (compare to wikipedia pages)
  2. Clicking it presents the discussion (e.g it either flips the view because it is a tab or maybe it just opens a dedicated tiddler). For posting, there is a link that navigates to the discussion on talk.tiddlywiki
  3. …and/but if there exists no such discussion thread then the link (or possibly the button described in bullet 1) asks if the user wants to navigate to the forum and, in the process, also automatically create a new thread which has its URL autogenerated based on the tiddler title and modified date.
2 Likes
#27

Posts here can be edited for a limited amount of time, for the exact same reason. …
eg:

  • I post: “Ths is a test”
  • You post: "There is a typo in ‘Ths’ it may be “This”
  • I change my first post to: “This is a test”

The reader will see

  • My post: “This is a test”
  • Your post: "There is a type in “Ths” it may be “This”

So the only typo is in your post now. … For that reason editing is locked after some time. Threads can become super strange, if there are replies already.

#28

So you volunteer to be responsible for manually fixing discussions about documentations … 24/7. … right?

IMO It has to be automated as much as possible.

#29

OK, well, the idea to edit the top post is only for convenience for the reader. I guess anyone can just make a regular post to the thread with a link to any older versions of the discussion. Again, I suspect it won’t be that common to want to bring up old versions of docs. My point is to solve the problem with “out of date discussions” that you bring up, and I think this is easily solved if we use this “modified” url to simply create a new discussion thread whenever a doc tiddler is updated. The old thread is still available, but it is not what is presented as the discussion.

Simple.

#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?