Reader-driven documentation development

Community Projects Documentation
#1

Hallo everybody,
I’m completely unaware of how the process of writing TW documentation unrolls, so forgive me if my proposal is misplaced or not new.
I hereby propose to shift to a reader-driven process to develop TW documentation in which readers submit ‘in-place’ feedback to improve it. To do so, we need some kind of ‘discussion’ page parallel to every documentation’s page, like wikipedia’s ‘talk’. This would be, in my honest opinion, a great contribution to steering TW documentation towards a clear, complete, flawless, useful resource: one thing is submitting requests of modification/improvement to some online forum whatsoever (like this one for example) one other thing is having readers’ feedback available where the document is, it can boost the improvement of the documentation by an order of magnitude I dare say.

Thanks and regards to everyone,
CG

1 Like
Attempting to use the "Reader-driven doc dev" test demo denied
Attempting to use the "Reader-driven doc dev" test demo denied
#2

I’ve been suggesting something like that.

If folk want to try the sample in the following post: The kind of workflow I like for collaboration on documentation

1 Like
#3

@pmario recently released Use TiddlyWiki to Contribute to the TiddlyWiki Documentation , giving an overview of a hopefully less cumbersome process to submit changes to the documentation via Github. This Category on Discouse is the right place if you want to discuss any areas you see needing improvement.

#4

thanks, I had indeed read your proposal. It is interesting and in tune with the collaborative development my post was about. Personally, I would lean towards a ‘discussion’ page parallel to the doc page it refers to, like Wikipedia has. I think that’s the simplest and most effective way to go.

#5

thank you, @pmario 's approach targets a much more skilled user than I had in mind, more knowledgeable of TW’s nuts and bolts than the average one: a true ‘editor’ in full standing. What I propose can be viewed as complementary to his approach, as the lower layer for a much less skilled (say newbie to average), less ‘involved’ (and by consequence much larger) user base, of people who just comes across a bit of documentation that they find inconsistent, confusing or whatever and drop their modification proposal there next to it, so for it to be read by some ‘official’, or ‘registered’ editor/reviewer/publisher (call him what you want) and, if approved, be incorporated in the documentation page.
Apart from highlighting passages not clear ot not complete enough, the other useful side of having a ‘discussion’ page would be indeed …the discussion. It gives a valuable, in-place feedback to TW documentation’s editors and publishers on how the documentation itself is understood -or misunderstood- by the users and how they would like it to be.

#6

I’m not sure if you are suggesting implementing Wikipedia’s (well, MediaWiki’s) discussion feature in TiddlyWiki.

If so, I don’t think TiddlyWiki can handle that kind of thing. (Well, if it can, that would be pretty awesome.)

If not so: Building and hosting a MediaWiki instance for this kind of thing seems like a not so great idea to me when there are existing really user-friendly solutions for having discussions about a document / content and even granular permissions for collaborating on a document / content (I favour either Google Drive or Notion, but I’m sure there are other products that handle discussions/comments, and “resolving”, that are just as nice.)

That said, it would be nice to see discussions in Wikipedia/MediaWiki to compare. I’m thinking it isn’t as user-friendly, but I may have missed something.

#7

Here’s what maybe could be done:

There could be a button in each doc tiddler that simply leads to this forum or, rather, a specific thread in this forum, dedicated to that specific tiddler. If no such thread exists, then it is automatically created when you click the button. The thread (originally) contains the raw tiddler text as its first post. But this is intended to be edited based on consensus, i.e the remainder of the thread is where discussion takes place and ideas and modifications are proposed. When people agree the, then modified, top post is an improvement over the original then it is submitted as a PR.

1 Like
#8

That sounds like a great idea if technically possible. I kind of suspect that it is not, because if you could make a thread just by clicking on a link imagine how easy it would be to spam the forum? Maybe @boris could comment?

An alternative would be that there could be a category called “TiddlyWiki Tiddlers”, where each thread is started with the exact name of TW tiddler. There could be explanatory text at the top.

#9

Discourse comments CAN be embedded on a per static page basis, which would automatically create new threads here.

BUT … as I have re-iterated before:

  1. start by doing it manually. Let’s see if this will get used and is useful.

Want to update docs? Great! Copy the comments into a post here on discourse in this Documentation category, make it a wiki, and work collaboratively with others to make and discuss changes.

There are no blockers to doing this today.

  1. if it works, someone can volunteer to implement Discourse comment embedding as part of TWdotCom static docs

This will require some basic front end dev skills and isn’t onerous. Jeremy would need to approve changes submitted.

#10

As per the sample document I had setup, it demonstrates that proximity is king.

There’s the highlighted snippet, and there is the comment related to that snippet. And the whole discussion thread. All right there.

To me, that’s a utopian approach. But hey, whatever floats the most boats is what will the best documentation and documentation process create, me thinks.

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