You should. (plus more needless but obligatory characters)
Wow: as a naive user of Github (in single-user mode), i had no idea all this branching/ merging stuff was so complicated! Considering this, i resonate most strongly w/ this comment:
YES indeed: Why canāt we do this collaborative documentation-building stuff in wiki? Clearly we can -examples all over the web abound- but doing it in TIDDLYwiki seems like a big hairy challenge, because the technology architecture does not lend itself easily to multi-contributor workflowsā¦ And doing it in some other flavor of tech, like MediaWiki or such, would be like a confession of our own inadequacy. Is that a fair statement of the problem?
If it is, then iād be inclined to let go of tech bias for a bit (at least until one of those multi-user TW development initiatives iāve heard bandied about yields production-ready fruit), and consider a fork of some proven solution to this problem.
Most obviously: Wikimedia Foundation has spawned a host of good examples -including Wikimedia Commons, a āgene bankā of resources that we might do well to integrate at a deeper level, i would say- and while all this is going on, our patron saint Ward Cunningham has not been standing still; his Smallest Federated Wiki project implements some very interesting ideas about how a wiki community might rip/mix/burn each others content in a most fruitful way. Still needs somebody(s) to edit & publish the canonical content-set in our particular UseCaseā¦ But as this is being done anyway (by @jeremyruston , i presume), what weāre talking about here is how that process might be made more efficient and/or effective by throwing the weight of a wiki-powered community behind it.
I donāt expect thereās anything new in what iām saying for all you veteran wiki-weaversā¦ Yet perhaps the idea of using wiki-tech to build better docs in a more collaborative way is one whose time has come (?) If so, then iād be happy to contribute to that effort.
/walt
The problem is that the current GitHub based flow is too complex and this blocks further participation.
The second problem is no one is volunteering to spend time figuring out if a different TW flow is possible by owning the issue with a group of 2-3 people to start.
Thatās not me āpointing fingersā just pointing out that there doesnāt appear to be enough bandwidth in the community.
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.
1 Like
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;
- Understanding all the documentation macros without committing to research and regular submissions.
- There is no user document for the use and standards for documentation macros, only a documentation of the macros. Trouble is you must understand it all before you can start.
- I would prefer to preview my changes in tiddlywiki and only then review a difference in Github.
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