Tiddlywiki5: How can we improve the experience for people who want to contribute to the documentation?

[ldorigo]

3313 Highlighted the fact that the current system for improving the documentation is unsatisfactory, mainly because it forces non-technical people to interact with the confusing system of Github and pull requests.

To keep that issue focused on its original intent I propose to continue the discussion regarding documentation on this one.

[sukima]

Proposal

What if we separate the code and the tw5.com edition documentation into two projects. Code can continue to get issues/bugs reports and plenty of Pull Requests. While contributions to the main tiddlywiki.com site can be managed in a different process like email, google groups, Trello boards, etc. Or maybe some custom EC2 app that posts to GitHub on behalf of the contributor.

Anyway the intent would be to separate the common types of contributions which (if my understanding of these complaints is correct) Falls under two gourps:

| Type | Scope |
|----|----|
| Coding | Anything concerning JavaScript. Things like plugins and anything in the core/ folder |
| Non-Technical | Anything concerning a *.tid file. Things like documentation, translations, etc. Anything in the editions/ folder. |

We also should consider alternative communication tools and process. At this time I know of three categories of communication.

| Type | Scope | Forum |
|----|----|----|
| Technical | Things like how we manage JavaScript patterns, code architecture, build systems, devops for the main site, and tools to enable user contributions. | Git and GitHub or other developer friendly tools |
| User Experiences | Things like Bug reports, feature requests, meta conversations like these. Constructive conversations on how things could be improved or alternative was of doing things | We have two at the moment, GH issues and Google Groups |
| Help/How-Tos | Things like asking for help. How-To topics. Examples, and mostly anything related to the use of TW without any changes to the repo. | Currently we have two: GitHub issues and Google Groups |

Some resources on the topic of GitHub and non-technicals

• https://github.com/dwyl/github-reference
• https://www.amazon.com/Introducing-GitHub-Non-Technical-Peter-Bell/dp/1491949740
• https://jarboo.com/resources/git-for-non-programmers/
• http://www.madebyloren.com/posts/github-for-writers
• https://www.chronicle.com/blogs/profhacker/the-limitations-of-github-for-writers/48299

[ldorigo]

Separating the documentation from the main project seems like a very sane idea, I don't know why it wasn't done like that in the first place.

Your separation of scopes is maybe not so accurate, as a big part of TW is actually coded in WikiText, in tiddlers. So many *.tid files contain code. I would limit it to "Anything in the editions/ folder."

Regarding the communication channels, your table makes sense. Here's how I see the optimal solution:

Type | Scope | Goal
-- | -- | --
Technical | Things like how we manage JavaScript patterns, code architecture, build systems, devops for the main site, and tools to enable user contributions. | GitHub, #tiddlywiki-dev and "dev" room on the Gitter chat. Dev group on google groups.
User Experiences | Things like Bug reports, feature requests, meta conversations like these. Constructive conversations on how things could be improved or alternative was of doing things | User feedback platform, currently in the works with @pmario
Help/How-Tos | Things like asking for help. How-To topics. Examples, and mostly anything related to the use of TW without any changes to the repo. | Google groups for larger questions, https://gitter.im/TiddlyWiki/public and #tiddlywiki for chat

[Jermolene]

I am against taking the core reference documentation out of the main repo for several reasons:

• The core reference documentation is the authoritative source of reference information for TiddlyWiki
• Being in the same repo means that TW users can pick up a single ZIP files that they can be confident contains everything that they need to use TiddlyWiki
• Being in the same repo means that it is possible for people to submit PRs that change a core widget and also update the docs in one go

Instead, I'd like to split the more ephemeral documentation out of the core repo (ie, all the community stuff like examples, resources, links, hints and tips, etc) and into an online tool that's easy for TiddlyWiki users to edit and/or submit. Then the new build process would pull that content when building tw.com.

[AnthonyMuscio]

Jeremy, Supporting your idea could we have this community version include all tiddlers on TiddlyWiki.com such that contributions can be placed against existing tiddlers, an example may be that I provide some example code, or a alternative description or even simple copy-able syntax in the community platform, then you make this accessible from the TiddlyWiki.com tiddlers like a per tiddler link to community contributions. It would be a simple matter of having tiddlers in the community tagged with the tiddler they are contributing to in tiddlywiki.com (or empty). In time, selected and authorised users, can use the appropriate method to move useful contributions into the original tiddler.

[rmunn]

Here's one idea that occurs to me for making the documentation easier for users to edit. (And maybe you've already done this or something substantially like it, @Jermolene, in which case disregard this comment on a two-year-old issue).

1. Have one copy of TW running on TiddlyWiki.com, serving up the tw5.com edition.
2. Have another copy running somewhere else, say jermolene.github.io (or tiddlywiki.github.io if you've already created the tiddlywiki organization), serving up the tw5.com-docs edition.
3. The tw5.com edition would contain text when you edit a tiddler that says "You can edit this copy of TiddlyWiki to experiment. This edit is temporary, will not be saved anywhere except in your local browser, and will be lost if you refresh the page. If you are trying to edit the tiddlywiki.com documentation, please go _here_ and submit your edits on that site instead." (Where _here_ is a link to the github.io hosted site, whatever its address ends up being).
4. The tw5.com-docs edition contains a button or a tiddler called "Suggest documentation changes", with instruction text. What it boils down to is that you can review the changes you've made, uncheck a checbox (default checked) for each modified tiddler, and fill in your name & email address at the bottom of the form before hitting a Submit button (or check a box that says "I don't want to be contacted about my suggestion"). If you have either checked the box or filled in a name and email address, then the Submit button is active and can be clicked.
5. When you click the Submit button on the tw5.com-docs edition, it uses the GitHub API to create a PR. The GItHub user that "owns" the PR will be something like "tw5-docs-bot" or something. (How the bot's GitHub API key can be kept secret when it's sent to users' browsers in Javascript is a tricky question; I have an idea or two, which I'll mention below). The description of the PR will include the user's submitted name and email address, and/or "Anonymous" if they checked the "do not contact me" box. The content of the PR is, of course, the content of the tiddlers that the user changed.

Possible problems:

1. Might also need the user to explicitly check a checkbox that says "I assign copyright to Jeremy Ruston/the TiddlyWiki Contributors/whoever on the material that I'm submitting". Or if you think assigning copyright is something people might balk at, license the documentation under a CC license or MIT or something, and have the checkbox say "I grant anyone in the world permission to use my material under the MIT license terms (link to MIT license text)." Otherwise we could end up with doc submissings that couldn't be legally used because the user made substantial changes, owns copyright in their changes, and did not give an explicit license to use them. (I'd guess that 98% of people submitting documentation changes would want to license them for anyone to use, but most people aren't aware of the intricacies of international copyright treaties and laws.)
2. Security issues for the bot that creates PRs. Maybe the submit button just sends a POST to a server, say in a subdomain of tiddlywiki.com, and the server code is what actually creates the PR. That way the GitHub API key can be held by the server code and never exposed to the user.
3. Is the user submitting a PR based on an out-of-date browser tab they've had sitting around for a month? Maybe the tw5.com-docs edition includes a state tiddler that says "the current HEAD commit in the repo is 123abc456", and when the user hits the Submit button, that state tiddler is sent along with the rest. Then the server creates a PR based off of the HEAD commit that the user had, so that the changes the user made are exactly the changes contained in the created PR. If the PR is too old, then it will create merge conflicts, but it shouldn't be too hard for an experienced developer to look at the resulting PR and rebase it as needed.