Is this how you "review a PR" ?

[twMat]

Apropos this discussion, I'm wondering if I understand the following right.

If I want to "review a doc", take this one for a totally arbitrary example, I go to that link and click the "Files changed" tab. Therein I get the following view and the idea is that "to review" means to painstakingly trod through this UI and, if some discrepancy is found, click on individual lines to make a comment.
Is that what "to review" a doc PR means?

[Jermolene]

If I want to "review a doc", take this one for a totally arbitrary example, I go to that link and click the "Files changed" tab. Therein I get the following view and the idea is that "to review" means to painstakingly trod through this UI and, if some discrepancy is found, click on individual lines to make a comment. Is that what "to review" a doc PR means?

That is correct, it can be a lot of work. It can be a tricky, intricate task, and mistakes can be hard to spot once the PR is merged. PR review is our primary tool for maintaining the quality of TiddlyWiki (and the docs) and so demands careful attention.

[twMat]

Thanks.

Considering how, specifically, docs are intended to show up in tiddlers rendered with styling etc, it would be substantially simpler and less error prone if one could see the output while editing like in the tiddler editview preview pane. What would you say is the simplest way to get the docs PR into a tiddler(s)?

(TW is of course also an environment that every community member is familiar with. And if it is in ones own wiki, then it includes all the conveniences that one has installed for editing.)

[Jermolene]

Considering how, specifically, docs are intended to show up in tiddlers rendered with styling etc, it would be substantially simpler and less error prone if one could see the output while editing like in the tiddler editview preview pane. What would you say is the simplest way to get the docs PR into a tiddler(s)?

What do you mean by "while editing"? I thought the question was about reviewing the changes in a PR rather than editing a PR. We have the Netflix PR previews but they don't provide a means to list the tiddlers that have been changed in the PR, nor can one see the diffs with the previous content.

A community instance of MWS might be a good path to a decent editing experience for the documentation. The idea would be to make the docs available in a bag. To propose edits a contributor would create a new bag and a recipe that includes the new bag and the docs bag. Then the contributor visits the wiki of that recipe to make the edits. Once complete, the contributor notifies the editor who can review the changes between the two bags and merge them back if they approve. Essentially it would be the GitHub workflow but in TiddlyWiki form. We could build an arbitrarily friendly user interface.

An alternative quick and dirty path might be to have a CI script that generates a before and after static representation from https://tiddlywiki.com/alltiddlers.html, and then applies an HTML diff (ie a diff algorithm that shows diffs in the HTML output rather than the HTML source). However, the fundamental problem here is that the rich previews don't show most wikitext and so the reviewer would not be seeing all the changes.

[twMat]

What do you mean by "while editing"? I thought the question was about reviewing the changes in a PR rather than editing a PR.

In my mind, but I may be wrong, "to review" is to edit a PR by proposing suggestions as is done in the image here above, that the original author can then "accept" into the PR. Sorry if I don't understand the exact definitions.

A community instance of MWS [...]

I think a TW based tool for collaboratively developing docs would be extremely useful (and I imagine it would go hand in hand with several other "social" ideas for TW that I've long envisioned). IMO it is clear that github itself is a bottleneck for participation in the development of the TW project, because even advanced TW users are not necessarily coders.

What would it take for such an idea to become reality?

[Jermolene]

In my mind, but I may be wrong, "to review" is to edit a PR by proposing suggestions as is done in the image here above, that the original author can then "accept" into the PR. Sorry if I don't understand the exact definitions.

The UI shown above is purely for commenting; it is not possible for a reviewer to propose a change such that it can be accepted with a click, unless the reviewer makes a pull request.

A community instance of MWS [...]

I think a TW based tool for collaboratively developing docs would be extremely useful (and I imagine it would go hand in hand with several other "social" ideas for TW that I've long envisioned). IMO it is clear that github itself is a bottleneck for participation in the development of the TW project, because even advanced TW users are not necessarily coders.

What would it take for such an idea to become reality?

A great deal more work than improving what we've got: https://saqimtiaz.github.io/tw5-docs-pr-maker/

[pmario]

The UI shown above is purely for commenting; it is not possible for a reviewer to propose a change such that it can be accepted with a click, unless the reviewer makes a pull request.

There is a possibility for commenters to directly suggest changes to the code, that the PR creator can accept with a click of a button.

In the screenshot below, there is the first "+-" toolbar button, that creates the "suggestion comment"

So changes to a PR can be suggested on a line by line basis if needed.

[pmario]

In late 2022 I did create a wiki post at Talk: 7 Steps to Improve the TiddlyWiki Documentation -- I thought that's a cool name for a wiki-post.

The wiki is a bit outdated, because the tw5-docs-pr-maker has improved quite a bit. (I will try to update the wiki when I have time)

• It allows new users to sign the TW CLA (Contributor license agreement)
• The backup step is not needed anymore, since the pr-maker can load an existing PR from GH, so it can be changed and re-submitted

I personally think this tool is extremely useful, since I can directly see, how a change or a new tiddler will look like.

The acceptance of the community is very very low. There have been several discussions at Talk, which I did not join. Instead I did open the PR-maker and changed the content of tiddlers mentioned in the discussion. Push the create PR button and done. All of this is way less work than long-winded discussions about missing documentation.

[saqimtiaz]

It is particularly frustrating that the community at large won't even try the PR maker before rejecting it out of hand.

[twMat]

[Jeremy] A great deal more work than improving what we've got: ...tw5-docs-pr-maker
[Saq] ... the community at large won't even try the PR maker before rejecting it out of hand.
[Mario] 7 Steps to Improve the TiddlyWiki Documentation

I can't speak for anyone else but I can make a guess. People do want to contribute (we see daily evidence of this on the boards) but evidently none of the alternatives to do so are convenient enough. I can detail exactly what I think is insufficient with the existing alternatives but since people evidently don't use them, the more interesting question is if there are better ways regardless and I've already outlined a concrete solution for that that I think removes pretty much all hurdles for anyone.

[saqimtiaz]

I can detail exactly what I think is insufficient with the existing alternatives but since people evidently don't use them

By that logic, there is no reason to think any new solution will have better adoption. I can count on one hand the number of people that have actually read the instrcutions and tried the PR maker process once, let alone reported feedback, so it is not as if the lack of uptake is due to their experience.

Building infrastructure for the community takes time and signficant effort from volunteers, and is always a gradual process of iteration. If there is no willingness to engage with what has already been worked on, there is no motivation for myself as a contributor to try to improve upon what is there, let alone even consider new proposals. This is a personal position and not one that reflects the view of the project or any other developer.

I've already outlined a concrete solution for that that I think removes pretty much all hurdles for anyone.

It would arguably take me just as long to read that and reflect on that proposal, as it would for others to try the PR maker process. As we can see, neither has had much interest.

[twMat]

it is not as if the lack of uptake is due to their experience.

I don't think that conclusion is correct. But instead of guessing, let's ask.
@pmario , can polls on the forum be totally anonymous? And do they, in the same poll, allow for preformulated answers and a final "other reasons, fill in you answer"-alternative?

[...] no motivation for myself as a contributor to try to improve upon what is there, let alone even consider new proposals. This is a personal position and not one that reflects the view of the project or any other developer.

That position is, of course, fair and I feel your pain (e.g TWederation and TiddlyGoo took significant efforts and led to absolutely nothing)

I've already outlined a concrete solution for that that I think removes pretty much all hurdles for anyone.

[...] As we can see, neither has had much interest.

Do you have any guess as to why my idea has not gained any interest (from people who understand it)? Is it just too long to read? Is the proposal itself bad (in brief, the idea is to let people edit doc tiddlers in their own TWs which has to be publicly hosted on tiddlyhost.A central public wiki then fetches their drafts. The central wiki can in itself be a doc reference, but tiddlers can also be posted as PRs here on gh).

Thanks!

[saqimtiaz]

Do you have any guess as to why my idea has not gained any interest (from people who understand it)?

I can only speak for myself. You lost me at the initial disclaimer rejecting any discussion of alternative or existing solutions, which completely disregards significant work that has been done in this area and which I am not entirely sure you are actually familiar with. I completely empathasize if the intent was to just prevent conversation from veering vastly off topic as if often does, but I felt it came across as dismissive of existing efforts in the area and showed a lack of willingness to engage constructively.

I honestly didn't read past that point. It is difficult to find the motivation to engage with proposals for new ideas, when they are accompanied by a lack of engagement with - let alone brief feedback on - work that has already been done in the same area.

[twMat]

Valuable to know, thanks!

You lost me at the initial disclaimer

I don't know how else to prevent "off topic" other than to state it (...which nobody ever does and hence the inevitable results in discussions of comparable complexity). I really felt (and feel) the particular idea was too valuable to risk it being sidetracked (when other ideas can simply be raised in a new thread) but clearly I failed if people didn't even read it because of that very disclaimar. How would you have done it if you had that goal? Thinking about it, maybe I should have posted it without the disclaimer and then I(!) should be the one to open another thread if needed (...and a third, and...)?

As for:

significant work that has been done in this area and which I am not entirely sure you are actually familiar with.

Since you address me now, and assuming you're referring to your docs-PR-maker:

I was pleasantly surprised yesterday when testing it because when I tested it years ago (which I did) it was much less polished. Well done! However, to me it still has the show-stopper for the target audience to use it .and it is something that is glossed over in the wizard - namely "create a gh account" and, even more problematic, create the access token. As noted in my post, I'm guessing that this is a show-stopper (but you are also guessing in your conclusion) and my argument is this: The main target group that this creation caters to are people that don't use github because the are afraid of it. The very access token step is exactly an illustration of this. That 50-centimerter page with options and checkboxes for cryptic settings, with an initial warning about "Set an expiry date for security!" would make any non-coder go "Uuuuuh... I do want to correct a few typos but I'm not desperate to do it!" I say this as someone who is not a coder and who does occasionally contribute doc PRs here via gh but who consistently have failed to make code PRs because, well, either I'm an idiot or the gh userface is just not user friendly enough. (Considering the millions of users gh has, I guess it's the former but that then probably goes for a lot of wanna-be-contributors-if-it-wasnt-for-github in our community)

As I indicate in my "concrete solution" I think the key is to look at the smallest common denominator for the potential contributors, and this is probably TW itself. That your docs-PR-maker centers around this is brilliant and the idea that it loads the latest TW edition is brilliant. But I think that if no gh was involved then the threshold would be still significantly lower and if the editing can even be done via ones own TW then that is yet better.

Further, as I hint at in my proposal, it is not necessarily so that someone who contributes to the docs (or code for that matter) is the same person who makes the actual github PR! I think we would encourage a much greater number of people to contribute if they could just "edit tiddlers directly" - and then someone else can realize that, yes, this is good so I'll make a PR for it.

The thing with my proposal is also that it, AFAICT, overlaps with other solutions we need for the community, namely collaborative editing and development of tiddlers. Considering our "competitors" we are definitely behind in "social" and it seems like a very reasonable thing to feature in the future, so contributing PRs could probably be similar to sharing just any tiddle with anyone. Or maybe I'm just naïve...

[saqimtiaz]

How would you have done it if you had that goal?

I would have either first taken my time to do due diligence on related efforts in the community, and in brief acknowledged them and what was still missing. Alternatively, you could have inquired about other efforts to facilitiate the documentation project that you might not be so familiar with. However, that's just me and it is possible the disclaimer wasn't as much of an issue for others.

I was pleasantly surprised yesterday when testing it because when I tested it years ago (which I did) it was much less polished. Well done!

I clearly recall when Mario asked you to try it, and to be completely honest I also clearly recall that the screenshot you posted of your effort showed that the instructions hadn't been followed at all, not even in broad strokes... Apart from the wizard/tour which replaces the need to read instructions (why doesn't anyone care to read any more?), the functionality has not changed. I am not assigning any blame at all here, if anything that in part prompted the work on the introductory tour/wizard.

I was pleasantly surprised yesterday when testing it because when I tested it years ago (which I did) it was much less polished. Well done! However, to me it still has the show-stopper for the target audience to use it .and it is something that is glossed over in the wizard - namely "create a gh account" and, even more problematic, create the access token.

I concur that needing to create a token isn't ideal, however at least one community member that is no more of a developer than yourself has tried the PR maker and even strongly advocated its use. I think the time it would take most of the community to get comfortable with the token generation screen is considerably less than it took to create the PR maker let alone, start on a new solution from scratch. Furthermore there are several community members who are not developers but GitHub users who have tackled access tokens for using the GitHub saver, but have not engaged with the PR maker at all despite voicing frustration about documentation. If the access token but is the stumbling block, it wasn't ever going to get better without feedback on that front and on whether the rest of the process was helpful.

The lack of engagement and feedback makes it difficult to know whether the rest of the workflow is useful and whether it is worth the time spent to improve upon further. I will stand by the statement that for anyone with a GitHub account the PR makers offers a far better experience than creating PRs in GitHub directly. As for the access token part, we discussed eventually implementing something like a sign-in with GitHub/Google/Talk.tiddlywiki option instead. However the lack of feedback and engagement has meant that it wasn't clear whether that effort was worthwhile, and the idea has been shelved long ago. This is the key problem with lack of engagement and feedback, it stalls the work regardless of whether it had potential, and also blocks exploration of new ideas because one isn't sure if the first idea was a dead-end or worth pursuing.

I don't really have much time to spare this summer to engage with this discussion further and I will be honest in stating that my priorities lie elsewhere at present. What I do want to point out to you is that your proposal - which I have just read - is something that would have to be approached piecemeal if at all to have any chance of success at all.

If you search on the forum you will finding existing solutions for one wiki to load tiddlers from another on TiddlyHost, and the PR maker is the exact tool that a non-technical user would need to submit a PR, as well as be able to respond to requests for any further changes to the PR. So I think you have the basic building blocks that your proposal would require, and I don't see any low hanging fruit in terms of making it significantly smoother or easier until MWS can offer a robut multiuser experience, which I would not expect for the near future.

Have a good weekend and rest of the summer Mat.

[twMat]

Thanks for your reply Saq and I'll take the opportunity to thank you for all your wonderful contributions! It is evident that both of us care for this project. 99% don't engage or contribute at all :-)

[saqimtiaz]

The feeling is mutual Mat, hence my engaging in this discussion instead of enoying the summer sun! :)

…

On Sat, 26 Jul 2025, 14:25 twMat, ***@***.***> wrote: Thanks for your reply Saq and I'll take the opportunity to thank you for all your wonderful contributions! It is evident that both of us care for this project. 99% don't engage or contribute at all :-) — Reply to this email directly, view it on GitHub <#9186 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAQT7AJXYTDPKO6PC6PGQL3KNXTBAVCNFSM6AAAAACCLWJ3KWVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTGOBZGYZDOOI> . You are receiving this because you commented.Message ID: ***@***.*** com>