Request for Help: Documentation/Demo/Working Examples

#2

Mohammad,

I support this initiative and will contribute. I would however voice a concern and a solution. As a super user rather than developer I am bound to the wiki way, I cant easily resort to the developer insight. I look closely at every feature and every release. Especially where I have a need I test out the new feature.

Concern: Many of the new features including some older ones come with very minimal documentation, they are not well understood or documented to begin with and this stays true for a long period. You can also see how possible solutions to live questions are rarely demonstrated using some of these features when one would think they could be. They may make sense to those involved in the development but often not to other users.

I personally have attempted to use such features myself and quite commonly find the release information and the PR of little or no use. Basically it can sometimes be too hard to learn how to use such a feature successfully or at all.

Solution: I think we should give the developers and people with a deeper understanding a place and encouragement, to provide some examples and informal descriptions and suggestions how to use these features, there is no need to demand full and appropriate documentation from developers, only that they brief us and show the way. Obsessives such as myself (perhaps you) will then explore them more fully, be able to solve problem’s with them and have the capacity to produce documentation in somewhat plain English and thus democratise them more. Once the ball starts rolling on a feature it starts to have a presence, ends up here in the community and good examples can fuel the documentation.

Some current release examples include the message catcher and event catcher widgets.

Honestly this is why I think too many features do not get out of the engineering lab, and thus the documentation is not able to grow. How can I document something well, if I do not know how to use it myself?. This also occurs with techniques used in the core. Many of these could be referenced and reused if the documentation was friendlier. An example is the newish layout feature, the UI is so deeply dependant on tiddlywiki bespoke CSS classes, it can be hard to get anywhere.

There are plenty of counter examples and helpful deeply aware people but it seems only chance if they get to provide that little extra insight needed.

1 Like
#3

@Mohammad there is a list of documentation tiddlers that need work and the vast majority of them do not need any special developer insight to write. Most of those topics that are listed as needing documentation should be familiar enough for users that have been fiddling with wikitext for a while.

Sadly there have only been two community members that have stepped up to contribute. Lots of gratitude and respect for @Mark_S and @btheado, thank you!

This is lack of contributions is particularly disappointing considering that the barriers to contributing to documentation are very low now. If people don’t like the format of the core documentation and want to write it differently, what is stopping them? Go for it. As you say, we could definitely benefit from other styles of documentation to complement the core reference documentation on tiddlywiki.com.

I must admit that I personally find it very frustrating when people just keep complaining without using any of that time constructively at all, that is not contributing to solving the problems where it is within there skillset to do so, and often just complaining because they haven’t thoroughly read the documentation that is already there. If people don’t want to contribute to solving what they see as problems with the documentation, who is that they expect to do so and why do they think that expectation is reasonable?

Either we all step up and fix the shortcomings together, or if the community wants developers to write the documentation for them, then let’s collect some funds and hire someone to do it…assuming anyone is even willing! Everyone involved in the project is a volunteer and I do think that what is being asked for - particularly of developers - is outside the scope of what one can reasonably and reliably expect of volunteers who already give a lot of their time to this project.

Last but not least, in my experience with open source projects of similar scale, TW documentation is actually very good

Apologies if this comes across as a bit of rant @Mohammad and it definitely isn’t aimed at you. I personally find the experience of being a developer contributing to this project to be an increasingly thankless job, wherein I often perceive my efforts to be met with hostility by the community, despite always striving to represent the needs of end users in discussions around the core.

2 Likes
#4

Ciao Mohammad

I’d certainly say that the TW operators are now vast in scope and function.

Like many things in TW I’d say it’s richness is also it’s difficulty.

Whilst I would love to see clearer docs I also find that we can’t impose responsibility for that on tiddlywiki.com.

I do think, though, that use cases showing where the operators are used, and how, is one way to go that could help comprehension of the richness of the operators.

My 2 cents,
TT

2 Likes
#5

Right. I’m no programmer, but AM very thankful for all your very extensive work. TBH, I think part of the issue is that there is a lacking overall “conceptual framework” that ordinary users could use to “bridge-the-gap” between developing and end-use. What happens “in-the-middle” is developers do tend to get treated poorly. They DO the work. But once it is done they tend to be ignored. It is an interesting issue that I think deserves being gone into more.

Just early thoughts
TT

1 Like
#6

I think the best approach here is to make the official documentation really good. 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.)

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. How do I set up my editing environment? How many changes should be included in each pull request? Are people going to look over it in detail? Is there specific formatting or macros I’m supposed to be using? 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? 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?

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.

It’s obviously not that I’m not willing to write about TiddlyWiki, because I wrote an entire freely available book about it – but with that I knew the answers to all these demotivating questions up front, because I made them up on the spot.

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).

If we want more contributions – and it seems like we certainly do – I think the question is, what can we do to make the TW docs experience more like that?

#7

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.

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.

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?

#8

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

#9

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.

1 Like
#10

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

#11

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.

2 Likes
#12

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 :slight_smile: .

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.

2 Likes
Suggested flow for getting started with improving documentation
#13
  • 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

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!

1 Like
#14

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 :smiley: ). I can’t hazard a solution. BUT acknowledgements of what you (and others) have done developmentally is the least we can do more.

#15

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

1 Like
#16

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

2 Likes
#17

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

Best, TT

#18

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).

1 Like
#19

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.

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.

3 Likes
#20

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.

1 Like
#21

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 :wink: