Request for Help: Documentation/Demo/Working Examples

[saqimtiaz]

@sobjornstad

Let me share why I haven’t contributed to the documentation (except to fix a couple of minor typos) – I don’t know how to get started or what to expect.

This will be a short reply for now because in all honesty, I’ve been dedicating time for TW (around documentation actually, hah!) these last 2-3 weeks that I really do not have to spare. However I wanted to make sure that I acknowledge that your contribution to the community with GTW is invaluable and as far as I am concerned, you are far and above doing your part and contributing to the community, even if it isn’t via contributing to the official docs.

@sobjornstad

As far as I can tell, there are no written standards about things like this (and if there are, I can’t find them, which is just as bad, functionally). I could get past these things, but I’m a busy guy and minor inconveniences and uncertainties are more than enough to turn my head the other way every time I briefly consider it.

Here is what we have so far that I can easily find in terms of standards on writing documentation:
https://tiddlywiki.com/#Documentation%20Style%20Guide:[[Documentation%20Style%20Guide]]%20[[Improving%20TiddlyWiki%20Documentation]]

What do you feel is missing? If we can come up with a list we can try to address those shortcomings.

Regarding how PRs are reviewed, @jeremyruston would be best placed to comment on that.

@sobjornstad

Similarly, I contribute to community wikis that use MediaWiki or similar pretty regularly, because there is none of this overhead. You click the “edit” button, there are instructions right there, and if you screw something up, you can trust that someone else will come along and fix it soon enough (and probably send you a message if you keep doing it).

Multi-user or collaborative TW is sadly still not on the near horizon but we have been doing work on making it easier to submit documentation PRs, where the process in broadstrokes looks like:

• edit a bunch of tiddlers in TW
• Fill in a PR title and description
• Hit submit

See: Edit documentation in TW and use Github API to create PRs directly?

[TiddlyTweeter]

@sobjornstad

Grok TiddlyWiki isn’t supposed to be an exhaustive reference of anything, much less filter operators. (This said, it is a little bit light on filters right now and I hope to add one or two more sections in a future version.)

I’d say Grok is very good in the sense that a beginner could at least get a decent basic grasp of what a filter operator is from it. That is half the battle already. You did good.

There are so many filter operators now I’m not sure a complete overview of them all would be possible. Maybe this is a situation where “strategic demonstration” of major widely used operators might work well enough though?

Dunno, TT

[sobjornstad]

@TiddlyTweeter

There are so many filter operators now I’m not sure a complete overview of them all would be possible. Maybe this is a situation where “strategic demonstration” of major widely used operators might though?

Right, I think the opportunity for improvement here is more that there isn’t enough practice with more complex filters, not that there should be a ton more operators discussed – though adding that practice will be an opportunity to see if there are important operators that have been left out.

[TiddlyTweeter]

@saqimtiaz

This is lack of contributions is particularly disappointing considering that the barriers to contributing to documentation are very low now. I

Ciao @saqimtiaz, I’m not sure you want to hear this but I don’t think it is lack of will. Rather it is lack of numbers. The pool of people both equipped to comment, with time and interest, I think is small.

Best, TT

[saqimtiaz]

I am not surprised in the least to hear that and do agree that is part of the problem. However, there seems to be a small chorus of voices that are always amongst the loudest and never lack time when it comes to complaining about documentation and ostensibly have the skills to contribute, yet there is nothing constructive forthcoming from them. My personal reaction then - whether right or wrong - is to disregard what they have to say until I see at least a fraction of that time and energy committed towards helping towards solutions.

If the problem is that we don’t have enough community members with the necessary technical background to contribute - which isn’t necessarily the real issue for documentation at least in my opinion- it doesn’t help that this community in recent times has become rather hostile towards newcomers that have a technical skillset. I’ve had one person confide in me that they backed off TW and the community as they felt bullied for asking questions about JavaScript, and another that I recommended to engage with “the very welcoming community” for further assistance that came back to say that from reading previous posts, it felt more like a lynch mob if you are a developer.

[sobjornstad]

@saqimtiaz

See: Edit documentation in TW and use Github API to create PRs directly?

Is anybody who has been following that thread able to easily summarize the current state of the initiative in 30 seconds for us? I tried to catch up on it the other day, but the thread had 61 posts, and after reading for upwards of 5 minutes I still had no idea where it was currently at, so I gave up .

@saqimtiaz

What do you feel is missing? If we can come up with a list we can try to address those shortcomings.

A few suggestions to start out:

1. Most importantly, I have never seen this documentation before, and I’ve actively tried to find it. We maybe have a general problem with organization on tiddlywiki.com, but also the place I look for information on contributing is on GitHub, not on the project’s user documentation site. For instance, there is a “Documentation” section in the “Community” section of the project README, which doesn’t say anything about this.

2. The section on documentation macros has no examples, so I don’t really understand where/how they are to be used. I don’t remember seeing most of these used when I randomly pop into edit mode throughout TW-com either, so if they are only used some of the time and the goal is to eventually get them used in more places, it would be nice to mention that.

3. It would be nice to have a clear list of things that we know need work so that new contributors know where to get started.

4. An explanation of the review/merge process, added to the section on “Improving TiddlyWiki Documentation”, would be helpful, especially for those who have never used GitHub.

5. If we want to encourage people to make bold changes, wiki-style, we should say that in the style guide or contributing guide. If there are caveats to that, or things that should be left for backwards compatibility, or whatever, that should be explained too. One of the biggest obstacles to me is that I have no idea what the community thinks is up for grabs when improving the docs and what’s better left alone. Either I have to ask a bunch of questions or risk spending a bunch of time doing something that proves to be useless.

Side note, have we considered displaying a list of sub-items (the tagged tiddlers) at the bottom of each tiddler (or somewhere else convenient) in the docs, if there are any? For instance “Improving TiddlyWiki Documentation” has a bunch of tiddlers below it, but unless you’re poking around in the TOC or go into the “Tagging” tab of the info screen, you have no way of knowing.

[saqimtiaz]

@sobjornstad

Is anybody who has been following that thread able to easily summarize the current state of the initiative in 30 seconds for us? I tried to catch up on it the other day, but the thread had 61 posts, and after reading for upwards of 5 minutes I still had no idea where it was currently at, so I gave up .

• Needs GitHub Account
• Needs Github Personal Access Token - which is unfortunate but there is a direct link to create a token that sets up the right permissions and the token is only ever saved in your browser.
• Edit tiddlers on a clone of tiddlywiki-com
• Fill in a form and hit submit to create a PR for documentation change.

It isn’t pretty and the UX could do with more work (I hacked this in a few hours staying up late one night), but it works and can be improved upon.

Link: TiddlyWiki — a non-linear personal web notebook

@sobjornstad

A few suggestions to start out:

Thank you @sobjornstad, I had a quick glance and that is all very useful. Let me come back to this later this week when I have a bit more breathing room from other demands on my time.

I having been idly thinking of a “Contributing to Documentation” portal of sorts that provides guidelines, rules etc and then directs users to a facility for submitting changes.

PS: Discourse reminders via bookmarks can be very useful!

[TiddlyTweeter]

@saqimtiaz

it doesn’t help that this community in recent times has become rather hostile towards newcomers that have a technical skillset. I’ve had one person confide in me that they backed off TW and the community as they felt bullied for asking questions about JavaScript

It is certainly true that recently several people came to TW with great skill, especially in JS. It is unfortunate some comments may have put some of them off. TW is unusual in that we have the whole mix of people who just want to use; a mid-group of evolving semi-literate DIY folk; and full-on folk with a Proper Developer Hat (like you ). I can’t hazard a solution. BUT acknowledgements of what you (and others) have done developmentally is the least we can do more.

[pmario]

@sobjornstad

For instance, there is a “Documentation” section in the “Community” section of the project README, which doesn’t say anything about this.

The readme.md you mention is auto-generated and could be changed with Saq’s wiki editing and pushing this tiddler: TiddlyWiki — a non-linear personal web notebook

[Mohammad]

@Mohammad

We cannot expect developers (few at the moment) can cover timely release, official docs and yet provide use cases, working examples, etc.

Hi @saqimtiaz - from the above statement in my first post in this thread, I clearly stated that we do not expect developers to prepare documentation/working examples/demos! So one times more I want to emphasize I announced here a Public Request for Help for improving docs on filters (in the hope more volunteers come and help)!

I also quite agree with @TW_Tones, if I want to write demo/docs for filters, I have to understand them first, if not I cannot develop working examples, use cases, this is where @TW_Tones correctly asked for some hints, explanations from developers and ask a volunteer member to complete the documentation!

I myself focused on scripting part of Tiddlywiki and TW-Scripts is the good example here! I also many times shared examples, tips, etc. in the group, where the purpose was only to let others know how it works and all of them take time!

The kookma plugins all have documentations, please have a look at Shiraz as an example and I tried to provide a good and enough information for users!

So, I want to say, I do not complain, I just started this thread to say, we love Tiddlywiki and please help to improve the filters documentation/demo/working examples!

Thank you and the time and talent of all developers are much appreciated!

Best wishes
Mohammad

[TiddlyTweeter]

@sobjornstad

A few suggestions to start out: (edited by me)

1. … I have never seen this documentation before… We maybe have a general problem with organization on tiddlywiki.com, but also the place I look for information on contributing is on GitHub, not on the project’s user documentation site…(GitHub - Jermolene/TiddlyWiki5: A self-contained JavaScript wiki for the browser, Node.js, AWS Lambda etc.), which doesn’t say anything about this.
2. The section on documentation macros has no examples, so I don’t really understand where/how they are to be used…
3. An explanation of the review/merge process, added to the section on “Improving TiddlyWiki Documentation”, would be helpful…
4. … One of the biggest obstacles to me is that I have no idea what the community thinks is up for grabs when improving the docs and what’s better left alone.

Basically if it confuses you it will leave me on the Old Town Road.

Best, TT

[Mark_S]

We still have the problem of delayed gratification. At this moment I have at least 4 PR’s (non tag) pending. None of them particular controversial. One of them provides examples for one of the many tm- messages. If it is approved, I may go on to write up examples and corrections for the other 20 messages. But as long as it sits there, I’m not doing another one because it might be that I would have to change something on ALL of them. The longer the delay, the more likely I am to lose interest and never come back to the project. Also, the more likely someone else is to make some other change, which will mean that the merge can’t be fast-forwarded.

When you’re working free, the only ‘payment’ is seeing your work get used. You don’t even get a name attribute (except if you want to read the github commit history log).

[saqimtiaz]

@TiddlyTweeter

It is certainly true that recently several people came to TW with great skill, especially in JS. It is unfortunate some comments may have put some of them off. TW is unusual in that we have the whole mix of people who just want to use; a mid-group of evolving semi-literate DIY folk; and full-on folk with a Proper Developer Hat (like you ).

I think what we all need to understand is that everyone gravitates towards what what they are used to. Non-technical new users want things to be similar to what they might be used to from elsewhere, maybe that is markdown or a sprinkling of wiki mark up. We go out of our way to accommodate them and help them feel welcome and get started.

It is important to understand that when someone with a technical skillset, let’s say a JavaScript developer, joins the community they are just as much at a loss as the non-technical new users. None of their prior skillset applies or is relevant in the world of wikitext. So it makes sense that they gravitate towards using what they know, and we should be just as patient with them. There is a lot more that could be said here - and probably should be - but that would probably take us even further off topic than I have already done, so if we want to discuss this further we best do so elsewhere.

@TiddlyTweeter

I can’t hazard a solution. BUT acknowledgements of what you (and others) have done developmentally is the least we can do more.

To be honest, personally I really don’t care about acknowledgement. I would be more than happy to keep doing my thing in the background and for no one to ever know about it or mention it, as long as we could stop with the uninformed hostility that new development work is sometimes met with, as well as the rather unreasonable statements that crop up far too often implying that developers are not doing enough.

[pmario]

@sobjornstad

How many changes should be included in each pull request?

IMO it depends on the size of the tiddler. I personally would go with 1 tiddler per PR if eg: 1/3rd of the content is changed or the internal structure is changed.

If you have more than 1 heavily modified tiddlers in 1 PR the chances are high that 1 tiddler is OK, but the other one causes problems. … So the whole thing can’t be immediately merged.

If it would be 2 PRs 1 could be merged and the other one may need some discussion.

BUT

If tiddlers belong together and changing 1 without the other doesn’t make sense, they should be in 1 PR.

[pmario]

@sobjornstad

Are people going to look over it in detail?

Yes. If we see a PR we generally have a look at the diffs. If something looks suspicious you can be sure that you’ll get a comment with our thoughts.

If every thing looks OK there only may be a “thumbs up”-emoji or a “looks good to me” comment. So Jeremy knows that someone else also has looked at it already.

The final decision is made by Jeremy. … and you can be sure that “backwards compatibility” is a thing

[saqimtiaz]

@Mohammad

if I want to write demo/docs for filters, I have to understand them first, if not I cannot develop working examples

@Mohammad if you look at the list I referenced, I am very confident that writing documentation for the following is well within the abilities of most of the people participating in this thread:

• Filter run prefix documentation tiddlers missing for most prefixes
  • even ignoring the newer prefixes, we need documentation for the very old ones like +, ~ and even the no prefix case. There are examples to follow that already exist for the structure of the documentation.
• Examples for insertbefore operator
• Examples missing for haschanged operator
• Provide examples for the ButtonWidget

From my point of view there isn’t much of argument to be made claiming that documentation cannot be written due to a lack of understanding, when the ones that easily could be written are still wanting for attention.

Furthermore, many cases of people claiming that documentation is lacking are not carefully reading what is already there.

Take the EventCatcherWidget for example, the documentation is complete and includes a functional example. It also mentions that it is an advanced widget that requires understanding of HTML and DOM events. It isn’t intended for everyone, we have other widgets that are easier to use and do not require such knowledge, the entire TiddlyWiki user interface has been built without EventCatcher for instance.

Teaching users about HTML and the DOM is far outside the scope of what TiddlyWiki documentation should be expected to explain. However for users willing to spend the time to understand the relevant concepts about the DOM, this opens up a lot of interesting possibilities without ever needing to write or understand JavaScript. This in itself is a significant achievement, it cannot be simplified further - well it can but then we end up with widgets like the ButtonWidget which we already have.

[TiddlyTweeter]

@saqimtiaz

… if we want to discuss this further we best do so elsewhere.

The issues you raised are very much about “perceptions”. I think they matter. I’m not sure how much we can address them. Just FYI I worked with “developers” in TW in a naive way to MY benefit. @pmario on Custom Markup and Bundler. @Mark_S on Polly. Moransanue on TW Icons. I think we get along.

I would happily comment in a new thread that champions developers. You are the rock stars.

TT

[pmario]

@sobjornstad

Is there specific formatting or macros I’m supposed to be using?

There is a Documentation Styleguide and it should be used.

But as you found out, there is room for improvement. … If I remember right, the “Documentation Macros” date back to some discussions with Tibias Beer about “improving the docs” 2014 or 2015. …

They should give us the possibility to globally “re-define” and “theme” doc-styles if the macros are consistently used in the docs. … (there is still some way to go)

They are mainly used with filter operator docs and scattered all over the other doc tiddlers.

[pmario]

@sobjornstad

Am I allowed to boldly reorganize things that I think are laid out badly, and if I’m not sure if something’s a good idea, where do I discuss that with other users?

If you try to completely change the structure, you should definitely discuss the new structure first. … The best way to go is “start small” …

Create a demo wiki with eg: 10 tiddlers that show the new structure and let’s discuss it – here or at GitHub Discussions

[pmario]

@sobjornstad

Once I spend a lot of time making changes, am I going to be asked to make a bunch of updates to it before it’s accepted? Even something as basic as, what branch do I submit changes to?

Yes. It may look like this, where I thought it would be a quick fix. … The bad thing is, it can be frustrating. … The good thing is: What ends up in the docs is better as the first try.