At the moment TW is a “mono-repo” where it is impossible to give different groups of users access to different elements of the repo.
IMO you have to convince Jeremy, to split the repo into elements that can be handled by different groups. … As long as we have a mono-repo, we will have to stay with the status quo.
The mono-repo and permissions is a challenge to some possible improvements. Branches, GitHub Savers, TW on NodeJS for editing, GitHub Actions, etc might be some tools that could help improve things. I don’t know, I don’t have time to invest in investigating further at the moment either.
To convince Jeremy of anything, someone will need to do some research and suggest solutions.
Firstly, without @jeremyruston’s agreement that “something needs to be done”, I’m not sure investing in a POC, theoretical or practical, is worth anyone’s effort.
Agreed, though perhaps “blocks” is too strong a word? The system is fine for people that spend half their dev/work time in GitHub on a regular basis. For others, it’s a hindrance at least – the on ramp too steep/too time costly, especially if what you’re trying to do is a quick/minor change to the wording. Yeah, perhaps “blocks” is the right word 
Agreed. tw.com is not Tiddlywiki. tw.com is an instance of Tiddlywiki. The “docs tiddlers” should be something else entirely.
I honestly don’t know where this topic is going 
Surely we could keep the docs tiddlers in a separate repo, but have a workflow that automatically merges changes discovered there into the main repo? (We might also need to back-propagate changes from the main repo into the separate repo, but that’s no big deal either.) IIRC we are already doing essentially that with the Links Aggregator (indeed, that workflow is a little more complicated since it has to do something with each of the repos it pulls, and any number of users can have their own repos). I was the lead on Azure DevOps pipelines (very similar to GitHub Actions) at my last job for several years, and my experience is you can make basically anything happen as long as you have a clear picture of what you want. The only challenge here would be merge conflicts.
If the problem is basically that there are too many buttons to click in GitHub, this would seem to solve that problem. Fork docs repo, clone to computer, run tiddlywiki --listen, make changes, push changes, PR to docs repo.
Obviously it would be nice for participation if we could edit directly on the web, but that would be a start, and pretty easy to implement.
Maybe Jeremy wants all the doc PRs to be within the same repo, though? That would be the only thing blocking this kind of a workflow as far as I can see. I’m not sure how important that is, though – the benefit is being able to see changes to the docs made in the same commit as changes to the code, but nothing in this workflow would preclude being able to do that, we’d just also have the option of making improvements to the docs unrelated to any code change in a more convenient way.
This is the kind of “let’s figure it out” process that some group of people need to take ownership of.
Are you interested in taking this on @sobjornstad?
Yes, good idea.
The TiddlyWiki project has benefited enormously from a strong international community, and I’ve always wanted to avoid it being yet another anglophone echo chamber. I’m keen to do anything we can to improve the experience of the software and the community for non-English speakers. When I write I try to keep my language usage clear, but of course it’s hard, and so any feedback is helpful.
It’s not much different. The docs on tiddlywiki.com include the canonical, authoritative reference documentation for TiddlyWiki. Users should expect them to be scrupulously accurate, even if they can never be fully complete, so the kind of submission/review process we have is appropriate for some of the material (even if the mechanism of that process is currently too complex).
I’m less sanguine. Discussions about documentation often end up considering the technical obstacles to contribution but I really think a bigger barrier is the point I mentioned above – the docs on tiddlywiki.com are the authoritative reference documentation for the system, and so they need to be accurate and consistent. That turns out to be quite hard, and requires extensive knowledge of TiddlyWiki, and the docs, and all the macros/styles/structures etc.
The reason that I’ve resisted splitting TiddlyWiki5 into multiple repositories is because I believe that it keeps things much simpler for users if the repo is completely self-contained, and that trumps having finer grained access control. It means that people who aren’t familiar with GitHub can still download everything they need with a single click (similarly not requiring knowledge of npm is why we don’t require the use of npm install).
That desire for all-in-oneness is not necessarily a constraint to operating in the way that @sobjornstad suggests, or in general pushing/pulling content from elsewhere.
No problem from me! Work on the documentation has gone in fits and starts over the years.
I see it. I don’t have problems with TiddlyWiki. I was talking about Git/GitHub.
Then maybe what is needed is some alternative platform where the requirements are not quite so stringent, but that users can more simply contribute. Just as there is beta software, so can there be beta documentation. As we know with software, sometimes a beta is more useful than a production version (because it has some essential but lightly tested feature). The documentation can then be eventually moved to the main documentation by individuals who don’t mind threading the needle occasionally. Speaking of language, contributors to the second phase would only have to be fluent in GitHub 
If this was some other project, by now someone would have set up a wikimedia, or fandom, wordpress, or other such site for accumulating knowledge. But I don’t think such a project would have “legs” here unless it had Jeremy’s blessing.
So I’ve tried this several times in this thread.
This doesn’t need “blessing up front”. Lots of kernels of ideas. It needs some people to take ownership and work the problem.
Once there is an example, proposal, a set of committed people — then @jeremyruston can say what he thinks. But without that — there isn’t anything to bless.
And we may be stuck at the “no one has time to commit” stage. Which is fine. The status quo remains until someone has time.
Thanks Jeremy for your feedback regarding the philosophy for the documentation. I agree the tiddlywiki.com documentation should maintain a high level of accuracy and keeping it within the main repo ensures that those involved in the core are double checking to make sure the documentation actually matches the behavior and functionality.
I’m willing to help as a committed person for the documentation. I think keeping discussions about documentation in Discourse can be the official way for people to make suggestions without needing to necessarily make commits in GitHub.
Alternately (and I know this may be a stretch) I think if Soren is willing to open up Grok TiddlyWiki for community contribution might be a good outlet for people if their suggestions don’t necessarily align with the tiddlywiki.com documentation philosophy.
Good discussion. A server running a community-edition of the tw.com docs that allows multi-user editing, which would be the responsibility of a small team to then Quality Control & submit PRs to the official repro would be a great use-case of my new multi-user tech. Gawds I need to figure out these last few bugs. 
I am prepared to step up but I am often pushed back by the complexity of GitHub which I have no personal or professional need to understand. Though I try and make do, documentation submissions are too time consuming for me to steal some time for.
You can see from my activity here I can write the content so I am ready and willing with a little more help.
However, I have not read this entire thread, I just wat to make sure your are all aware of the often missed way of contributing to documentation TiddlytWiki.com just in case.
Go to tiddlywiki and pick a tiddler and edit it, note the pink line;
Can you help us improve this documentation? eg;
Find out how to edit this tiddler on GitHub
Now the above links to the tiddler in GitHub.
The main impediments to contributing for me are;
I hope this helps if it was missed?
Perhaps the same mechaisium could be reviewed and allow edited documentation tiddlers be submitted to a queue that a small team then review and ensure “compliance” and submit to GitHub. With this operating we will quickly find ways to improve the process and the small team can make themselves obsolete.
Have you tried this? It simply isn’t that easy. First you have to have an account on GH. Then you have to sign the CFA (or whatever acronym). Then when you make the change a fork is surreptitiously created. You work from your fork. You need to activate the tiddlywiki.com branch. Then make your own branch. So you need to understand branches. The editor is minimal, not meant for TW, and it is very easy to make errors since you can’t see the outcome. When you’re done you have to make a PR request. And wait.
But this process isn’t really practical for large-scale work. You need to see what your tiddlers look like as your work. Cutting and pasting is prone to errors. And you need tiddler headers which are not provided in a standalone instance. So the practical way is clone your own fork and work from that. But then you have to maintain your fork and keep it up to date.
Anyways, the point is there is no way to escape from GH under the current system. Someone could offer to post others material, but that brings up the problem of attribution. Though maybe that’s not a problem since other than GH there is no attribution in TW. It truly is an egoless proposition.
Anyway, the point is there is no “click here” method to avoid the complexity of GH.
Why not deal with those issues as they arise? Most of the documentation doesn’t use special macros or formatting. And sometimes the official macros are a bit broken. Try your hand at documentation and see what the concerns with the GH system are.
You are right. The workflow has a lot of room for improvements.
It’s not a problem of “attribution”, it’s a problem of “licensing”, which we will find for all OpenSource projects. … They won’t be open source without those licenses.
TiddlyWiki uses the BSD 3 clause license since TiddlyWikiClassic 2004 …
GitHub [1] was founded 2008 and the Open Source Initiative has formed in 1998 [2] … Open source licensing has nothing to do with GitHub.
The Contributors License Agreement (CLA) [3] is 1 possibility to make sure the TiddlyWiki project is allowed to use code and prose text (documentation) without violating “other peoples rights”.
IMO TiddlyWiki can only be used in an “egoless” way because it is BSD licensed and has a CLA.
[1] GitHub - Wikipedia
[2] Open Source Initiative - Wikipedia
[3] https://github.com/Jermolene/TiddlyWiki5/tree/master/licenses
In the case of TW, I don’t know whose copyrighted resources could possibly be stolen. Is there some secret stash of TW docs out there we didn’t know about?
But my concern was whether I could, for instance, take Tony’s volunteered material and post it for him. I’ve signed the CLA. Tony hasn’t (or maybe he has, but for the purposes of this discussion let’s assume he hasn’t). What is the status of reposting material?
When I say “attribution”, I mean it’s almost impossible to tell, without wading knee deep in GitHub, where a particular update came from. There is nothing in the TW documentation to tell you who last submitted an update nor what part of the update was done by who. So that’s why it’s egoless. You will get no credit or recognition for your work.
For those who do want to peer into the inner workings, here is a direct link to the “history” of edits to what is live at tw.com:
https://github.com/Jermolene/TiddlyWiki5/commits/tiddlywiki-com/editions/tw5.com/tiddlers
A relatively small number of edits over time, but great to see a diversity of folks contributing this year!
As the CLA states the copyright isn’t touched by the licensing [1]. Every contributor will keep her/his copyright by contributing to the project. By signing the CLA every contributor grants the TW project a very “relaxed” license - forever.
See: 2.1.b of the CLA
(b) To the maximum extent permitted by the relevant law, You grant to Us a perpetual, worldwide, non-exclusive, transferable, royalty-free, irrevocable license under the Copyright covering the Contribution, with the right to sublicense such rights through multiple tiers of sublicensees, to reproduce, modify, display, perform and distribute the Contribution as part of the Material; provided that this license is conditioned upon compliance with Section 2.3.
PS: I’m not a lawyer, so everything mentioned here is my interpretation of how things work and therefore it may be wrong.
[1] https://github.com/Jermolene/TiddlyWiki5/blob/master/licenses/cla-individual.md#21-copyright-license
It actually is simple to know who contributed every character in a line of code and when. That’s one of the biggest advantages of git … See git … the underlying version control system used by GitHub.
See: https://github.com/Jermolene/TiddlyWiki5/blame/master/licenses/cla-individual.md#L1
Most editors that are aware of git have a possibility to show you the “commit history” of every single line in the code.
This mechanism makes it possible to tell what exactly changed between TW versions and which change caused an issue. …
You’re proving Mark’s point by wading knee deep into GitHub / git 
(I had to read the post twice myself but it also got me curious about finding the link)
The front end of TW doesn’t do any attribution. To me, that means some of us can wade in knee deep and highlight and thank those that do the work!
Thanks @pmario for your work!
@Mark_S it would have being sufficient to respond “yes I was aware of this and it dose not work for me”. But it helps that you spell it out.
I don’t like it either but I did not see this particular “feature” mentioned in this thread and wanted to ensure awareness of it.
Moving forward it is important we understand where we are starting.
Why not deal with those issues as they arise? Most of the documentation doesn’t use special macros or formatting. And sometimes the official macros are a bit broken. Try your hand at documentation and see what the concerns with the GH system are.
Well actually my point is these are a serious impediment for me and new users, to contribute document and if they ignore the macros new documentation will diverge from existing documentation. Just as you have found the github component unnecessarily complex.
