This is harvesting a bunch of the discussion from the original How To thread: Making changes to tiddlywiki.com via GitHub and Pull Requests (PR)
Please start new threads per suggested flow or improvement.
Yes @boris! Am strongly in favour of using Github PR process to develop and maintain tiddlywiki.com as “The Mother Ship” : canonical hub where all essential TW documentation is either hosted directly or linked in a most navigable way.
Moreover: That Documentation Style Guide is an excellent resource, which could really make our Mother Ship an example of best practice, to whatever extent it is followed. 3/4 of the GUT (Grand Unified Theory of Documentation) is held in its distinction between Reference and Instruction material, with the latter defining separate sections for both HowTo and Tutorial material. As to the 4th quadrant of GUT -i.e. Explanation- well… That’s what Talk.TiddlyWiki.org is for, isn’t it? Very important to maintain the distinction between these different forms of docs, which aforementioned Style Guide does in a clear and easy-to-follow way.
Let’s do this!
/walt
That would be nice, but I also think GitHub is too complicated for less technical users, so perhaps just offering to make PRs on behalf of users – with suggestions / discussions here – could get us there faster.
@ludwa6 are you comfortable using GitHub directly?
I wanted to document the process (as part of learning / discovering it myself), but I suspect that using Talk TW as a staging area where people comfortable making changes on GitHub could help make the commits.
What do you think?
Yes, in that i use it myself for branching docs w/ version control -even making the occasional PR to self 
Never yet in collaborative mode… But i’m game to play, as time permits.
+1 the idea of Talk TW as staging area -not only for shaping up robust PRs, but also Issues, which often emerge in this community as more or less vague tensions, which only develop into replicable problems after some back-and-forth Talk. Would be nice if every Issue in the tracker at Github were a problem replicable by a TW dev.
/walt
Good! … Just to be sure. I hope you starred the repo already 
You had me worried for a sec, @pmario -but indeed i have done, as it turns out, some time ago i guess. /w
Making PRs an behalf of others users is a lot more work than making your own PR.
Sometimes I do create issues on behalf of users, if I think, that something mentioned in a discussion actually is a bug, or it should be fixed in the core. …
This is just a “safety net” that it isn’t forgotten and it should encourages users to create issues at GitHub themself.
There is a bureaucratic necessity. … The CLA (Contributor License Agreement), which has to be signed by contributors. …
I know that this is an additional hurdle, but if someone did sign the CLA, they did create a PR against the master branch. … So if your first PR is merged, the workflow should be easier for the second one. … and so on
I’m also learnign it now. I have a two handicap with: the language and my “memory”.
- I don’t have good level in English. Google translate helps me a lot. But sometimes the meaning of words can be confusing.
- Verbose instruction does that i get lost, because i easily forget things.
For this I prefer the intructions with listed (short) steps. It can have introduction/description/etc. So I can easily see what was the last done step.
I have also discovered the problem of the conflicts. In my case when I have worked in an not updated branch and the master branch has changes in one of files which I modify in my PR. I have to learn how I can avoid it. In other words, I think that it would be that I don’t work in the lastest commit where the files of my PR have/had been modified.
Documentation via github is massively complicated. And it is made even more challenging by the “improvement” where everything goes under a separate branch. The documentation for this change consists of a SINGLE LINE (and yes, I am yelling because that is how I feel about it!).
If you already know GitHub, note that documentation updates must be directed to the
tiddlywiki-combranch
That’s it! What does “directed to” mean? How is it supposed to work? Why is anyone expected to know this? Shouldn’t there be at least a paragraph to explain how this works? And yes, maybe I should write it.
At this point, you’re having to push a sub-branch of a branch of a repository to a sub-branch of a branch of a fork of an upstream. And then the PR needs to be re-navigated to sync with the tiddlywiki-com branch. This is something that you will have a hard time even googling, because every google results in hundreds of answers to normal, regular github questions.
Does anyone really think this is reasonable?
And if you want to keep your local working repository in sync with the master, you’re going to have to know about fetch and merge on sub-branches, and once again all the standard stuff you find on Google will be inadequate.
If Github would let me, I would just make a different fork for every change I want to submit. That way everything would be up to date and almost simple. I would delete old forks and move on after the merge. But you can’t make a second fork.
Except they never had to make an offsite repository for that. And they had to make a tiny, simple text change. But if you’re going to make extensive changes, and don’t want to have it riddled with errors, you’re going to need your own local repository.
Oh, and now GH wants you to use a passcode instead of a password. Big long thing that you either need to paste in every time or write a script to insert.
You shouldn’t have to be a Github guru to submit documentation changes!
The things you pointed out are absolutely challenges and why it’s hard to move on editing documentation over time. If there is a goal of broader, non-developer participation in documentation improvements and maintenance, we as a community will have to work on this.
They are called branches, and you can do this. In fact, I just checked, and it does this by default:
This is me editing the readme file, and as you can see it is telling me it will create a new branch in my existing fork.
Your point still stands! Doing PRs that target a particular branch is a whole thing, but it’s a slippery slope to fully explaining how git works – and I don’t think teaching non-software-developers git is a useful path. It’s up to us to make this easier at other levels.
Hear bloody hear.
I started a little while back, jumped through the hoops (aided by @saqimtiaz - thanks Saq) then completely stopped. Life (mine, anyway) is far too short to waste it on that rigmarole.
My (not so) humble opinion…
@jeremyruston does a fantastic job of “policing” the code base – I have no issue there (nor do I participate, either). That is a key role and must be fostered and adhered to. But the docs? It’s a wiki, for crying out loud! I’d have no issue at all with some kind of clearing house/central control – which is what I think (strongly believe) Git allows.
But GitHub?
It’s insanely complicated. I’m no spring chicken, got the coding battle scars to prove it – but this is one war I don’t need to fight. The gaps between me doing something in the docs would mean keeping extensive notes (which I may or may not understand next time). The moment you take notes, you open another door: keeping the notes maintained. No thanks.
This woulda/coulda been my way of giving back – feels like the system said “no thanks”.
Github is git underneath, and unfortunately git by itself wouldn’t make this any easier, just less / different UI.
My ideas aren’t fully baked here, but I think something like using a tw.com download and the GitHub saver, or just documenting steps for running this on nodejs locally and committing to your own fork could be possible. Merging / PRs may still need to be done by git experts.
I think, like @markkerrigan’s suggestion of creating a documentation category, this is a “top level” community project. I suggested in that other thread:
So, who wants to work on this? Who wants to help improve documentation and be part of the Documentation contributors group?
Of course. Don’t teach grandpa to suck eggs Like I said, I’m no spring chicken.
But I’ve learnt that thick skins drawn over bare-metal commands can obscure the fundamentals to such a degree that sometimes they don’t help – they confuse. Having learnt that, I choose not to be confused. I did enough to prove it was a taxing task (for something that was inherently simplistic) and promptly did something far more constructive, instead.
Yes, I saw your posts. Good idea (I think).
No! No! No! Branches are NOT the same as forks. When I fork, I know everything is up to date. When I fetch and merge, I always have the feeling something is going to break, especially since it’s so poorly documented. (I mean, the Github stuff isn’t well documented beyond the very basics).
Even the Github CLI doesn’t give a good tool for viewing sub-branches. All the documentation is in terms of one-branch (usually main) and some very temporary working branch.
I want to start with a clean slate. Not be worried that a change I’m making is going to go to the wrong place and overwrite good stuff.
Once again, you’re working in a repository on a branch that’s a sub-branch of a branch that’s on a repository of fork of a project, and none of the documentation explains clearly what you do to fetch or pull in order to keep your site up to date. Try finding the documentation that explains that exact scenario!
To the casual user of Github, it’s a nightmare. Like I made some updates last month, but had to spend a half day reviewing because my last usage was in March. Conceptually, it would be easier to make a half dozen GH accounts and have a fork for each submission!
Wikipedia became the most successful encyclopedia on the planet because they made it easy to participate. It’s ironic that the documentation for a wiki can not be made as simply.
Branches is the common industry way to do this, with various techniques on how to update your branch / fork, which is most definitely out of scope of this thread – because that’s all targeted at software development of code, not documentation.
I don’t know what you mean by sub-branches, that’s not a thing in git or Github.
Again, I agree with you, and “casual user of Github” is a terrible experience.
We’re doing a very good job of highlighting that IF more documentation is desired, someone in the community is going to need to propose & work on some ways to improve this.
Do you have any suggestions?
Thanks @boris for tagging me here. I just want to chime in that unless you’re a GitHub expert, the process of doing the PR and forks can feel rather tedious.
I had helped a bit on the TiddlyWikiClassic documentation so I’m familiar with editing the .tid files and submitting the PR but I’m not a regular developer so it’s not in my muscle memory. But it’s easy to run out of steam on that. Simplifying the TiddlyWiki.com documentation process has been discussed before, but it seems like the process is still the same.
My thought on creating the Documentation Category is to have a singular place for discussions about documentation to exist. There are over 800 issues on the TiddlyWiki and this one about documentation, but it’s only likely to seen by people who are actively involved in following the GitHub. Also probably a more aggressive step would be simply to close all the issues related to documentation and direct those communications to the Discourse channel and people can submit PR when they have their actual fixes ready. Alternately someone can suggest improvements in the Discourse channel and someone who is GitHub savy can submit the PR.
Maybe this is considered off-topic, but documentation is one of the reasons I’m so interested in multi-user TiddlyWiki development. If TiddlyWiki.com had functionality like Wikipedia.org where anyone can edit it inline, it seems like a lot of barriers would be lowered. I think DocuWiki has something like that too… not 100% sure.
1 Like
Well, yes OT in that we’re now trying to figure out improvements / solutions
But you’re right — running TW.com in multi user mode could be a solution to improving docs flow.
This is totally doable!
“Somebody” has to stick up their hand and volunteer to organize a Documentation group.
I might just split parts of this thread back into Mark’s post?
I’m not opposed to creating a dedicated category — but for a category like this I’d like to also scale the responsibility. If three people say “I’ll help”, I can make a Docs group and away you go in figuring it out. Who wants to run with this?