Reader-driven documentation development

Community Projects Documentation
#11

There was an implied aspect to my idea but it was evidently too subtle:

The button would navigate to the thread whether the thread exists or not. Only if the thread did not exist is it created, but if it does exist then the button simply navigates to present the thread. This access is critical, also if we - as @boris advocates - create the threads manually. But it would not be realistic to create the links manually. (Other than spelling problems, what should happen if the thread title already exists?)

@jeremyruston - is there any way to include a link to here, per tiddler, on tiddlywiki.com? Maybe there could, in edit view, be a toggle to globally activate them, and once activated the links appear. It could all fit in the pink ribbon, I figure.

(To bypass the problem with such a thread already existing here, the link from tw .com could e.g have a specific prefix or some hash string.)

2 Likes
#12

I agree. But, as you say, it is utopian.

#13

Yes, Discourse can be configured to automate the creation of new threads on demand.

I’m not advocating for doing it manually. I’m saying — show that 2-3 people will actually improve docs manually … and then we can automate it.

#14

Yeah, thanks, I’m addressing Jeremy to hear if he is at all positive to featuring it on tiddlywiki.com

Gatcha :slight_smile:

#15

Why does it need to be in the static docs? Could it not be launched from TiddlyWik.com ?

Thanks!

#16

Yeah, but utopian doesn’t mean difficult to do.

In Doodling is critically lacking in TW!, the challenge of annotating text/content with doodles is utopian and not easy, but annotating with text (all kinds of collaboration tools for that) is really easy. And makes process / communication oh-so-smooth .

Whatever is more human-friendly (more inviting?) than 7 Steps to Improve the TiddlyWiki Documentation, which is great documentation about how to participate, although it immediately let’s me know that I can’t participate.

I’m guessing: anybody who may be talking about improving documentation but not diving in to help: boils down to process being the stumbling block. (Total aside: So anybody talking about that, it does demonstrate some passion for TiddlyWiki, and that’s good.)

All of which doesn’t matter one iota if folk are clambering over each other in an effort to help with documentation. Fix not what ain’t borked.

#17

I’m not thinking of any particular platform to implement my proposal, the only important thing is that each TW doc page has its own ‘discussion’ page clearly and immediately bound to it, so jumping from one to the other is a straightforward, zero-hurdles action.

#18

sounds pretty good! As you suggested, the button must enforce jumping to a dedicated discussion thread, the one and only thread officially devoted to discuss modifications to that particular doc page.

#19

proximity is king, true! Definitely! The ‘nearer’ the better. That’s why I had wikimedia’s discussions in mind as a solution to take as a reference model.

#20

It is the jumping that cognitively kills me.

Hence why I’m pushing hard for anything that can do what Google Sites and Notion can do: discussion is right there beside the thing being discussed.

Links from one web page to some other web page, one being discussion, the other the thing discussed, is really rough.

Maybe we are talking the same thing, I don’t know. If you can lob a picture into the discussion, that would be awesome.

#21

hmmm, I guess there is some misunderstanding that must be cleared here, because I think we have basically the same vision: editing things in place! When I speak of ‘jumping’ from the doc page to the discussion’s it is only for the sake of preserving a clean, readable doc page, nothing more. That said, the discussion page might well be made of an exact ‘replica’ of the doc page, edited and commented on at will. Yours indeed is a very effective approach, though it must be said in my opinion that comments in Google docs are a very limited tool, unsuitable to edit more than just a few words…

#22

Let’s not get too hung up on Google Docs. There are all kinds of tools that do the same thing.

That aside, a full and focused discussion in Google Drive anything seems to work well for me.

Good luck getting anybody to give it a proof-in-the-pudding college try with me.

#23

I think, it would be possible to establish links form the tiddler info area, or the “pink banner” to this forum.

There is a possibility to automatically create new topic with Discourse using URL links. … BUT I don’t know, how this mechanism behaves, if a topic already exists.

See: How to create a new topic link with pre-filled information - faq - Discourse Meta

Someone other than me would need to read the stuff and make some experiments.

#24

As I understand it, we ought to be able to embed Discourse discussion threads in TW, allowing something very similar to wikipedia’s Talk pages (albeit with the restriction that one needs to visit talk.tiddlywiki.org to actually leave a comment). See this earlier discussion:

https://talk.tiddlywiki.org/t/adding-discourse-discussion-threads-to-tiddlywiki-com-documentation/490

2 Likes
#25

I think the biggest problem (also with Wikipedia) with those discussions is, they are “out of date” as soon as a change has been made to the documentation. So the discussion – or parts of the discussion – have to be marked as obsolete, if the changes discussed have been made.

The discussions that happen on GitHub pull requests are automatically “closed” with the PR but they are there for ever in the database.

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