Request for Help: Documentation/Demo/Working Examples

#41

Yeah, I agree this forum isn’t the perfect place for a discussion like this, but I’m not aware of any existing forum that discusses documentation (which is one of the things I called out as a needed improvement).

Thanks for your thoughts too!

These have been submitted as pull requests, by people who had made good contributions at least once before, and in a manner that suggested they didn’t know there was a problem and they would have happily put it live directly if they could?

I’m not saying it doesn’t happen, I’m just pretty skeptical that it happens often enough and has large enough effects to be a major concern. I’ve overseen or participated in multiple projects where everyone was “Oh my god, anyone can edit this now!” and people have been convinced to give it a try, and it turned out not to be a problem at all.

This means the same documentation can end up in two places, which isn’t great since people already tend to have difficulty finding things. The “official” documentation can also end up languishing because it’s much harder to edit, and then the “community” documentation ends up being the definitive source. Maybe we would count that as a success if it happened and we don’t care, but it’s always a possibility.

Also, we don’t have enough people working on docs anyway, so adding a second docs site for people to divide their time between concerns me a little bit.

To me this creates an entirely different process than a separate “community” documentation site…we are really just delaying the review process, the eventual target is still the “official” site.

But I think this is a better idea than the previous one, and I could see this working effectively if we get the right process behind it. For instance:

  • It should be easy to access if you want to get the “latest.” Just like we have a prerelease accessible by adding /prerelease to the website, we could have a /latest or something (that’s not the best name, I can’t think of a better one right now). Most experienced users would probably want to use this version most of the time.
  • I’m not sure I like the “cherry-pick” idea – this seems hard, and if the changes in the official and the community documentation keep diverging, it will get harder every time (I know you can skip the commits that have already been merged, but you’re going to end up with more and more merge conflicts over time, which are even more of a pain to resolve in prose than they are in code). I feel like it would make more sense to do something like run a diff, identify anything that reviewers think is problematic, merge everything, and then make any required additional changes?

So maybe rather than a “community” edition, it could be essentially a “prerelease” edition of the documentation, only not tied to the release of a new TW version.

IMO, another sensible possibility that would accomplish the same goal of not making TW look bad to new users could be to protect (as discussed in my previous post) all tiddlers that are targeted at beginners. Newbies who would be turned off by bad grammar aren’t going to be reading the documentation on the $edit-text widget unless they get lost, so we could make those much easier to edit. On the other hand, plenty of the beginner stuff is underdocumented and needs work, so we might be blocking ourselves from effecting some of the changes we want if we did that.

I mean more or less everyone who set up and/or has previously been defending the current design, in my perception. (But I don’t want to put words in anybody’s mouth if they want to come forward and share different thoughts now!)

I’m game if others are willing to participate, although right this moment is not an ideal time for me (I’m in the middle of moving to a new city).

#42

I believe Boris was trying to address this need when the Documentation category was created, as well as the Documentation user group.

Do you think that would serve this need, or do you feel something different is required?

Regarding my concerns about poor documentation PR requests, and proposed idea for a community documentation wiki at .org, I think there are a couple of factors in my subconscious that are influencing my thinking, whether for better or worse. I will try to put those into words to help shed light on my thinking.

For starters, I am always in favour of trying to find a way forwards that does not rely on asking Jeremy to do even more to get us started, in many ways the community is over reliant on him in ways that hold us back. Changes to the official build process and site involve Jeremy, there is no way around that. So my natural tendency is to think in terms of approaches that the community could take that compliment the official site and mechanisms, at least until the new approaches are demonstrably beneficial enough that a discussion can then be had about making changes to the formal way of doing things.

You will see this reflected in things like the demo I set up for creating documentation PRs from within TW. I setup a mirror of tw-com that is fully functional. The idea being that if we can get it working well enough and it proves useful enough, then we can have a conversation about perhaps making that an official resource.

Secondly, Jeremy has previously expressed strong reservations about adopting a way of working that might allow the possibility of subpar changes to slip in to tiddlywiki.com. So my way of thinking has been to accept that as a constraint at least for now and try to work around it. The monorepo nature of the TiddlyWiki repository with no possibility for fine-grained permissions controls also plays into this way of thinking.

Right, that is a better framing of it than what I had presented. I think there is potential here that is worth considering further. I am also wondering how we could best incorporate tutorials, walkthroughs etc that might not be considered a good fit for the official reference documentation.

Personally I do think that the documentation for new users is probably the area that needs the most attention, so such a constrained solution may not get us very far in the long run.

No worries. I don’t know that anyone has really been defending the current design, personally its been a case of making the best of what we have!

I don’t think there is an acute sense of urgency on this, most things related to TiddlyWiki tend to take the longer and slower view of things. From my personal perspective, you would be an excellent candidate to be a part of a group taking the lead on this, and the community would be fortunate to have your participation.

I think the Discourse user group Documentation was created as a means for those wanting to work on documentation to identify themselves and eventually be able to collaborate. There is a link to join it here.

Apologies if any of this comes across a bit disjointed or rushed, currently juggling a few too many things.

2 Likes
#43

I am thankful for all the constructive discussions taking place herein and I sincerely apologize to @Mohammad for derailing this thread.

I have really overextended myself with work on TW community related things this week despite being in a time crunch at work, so it will probably be another couple of days before I can revisit this thread again.

2 Likes
#44

Thank you Saq for all your time, and help! No need to apologize at all! I myself learnt a lot!

Best wishes!

#45

@Mohammad and all, I want to contribute to the doc but the issue I face is that I’m not sure what’s expected to be in the doc and what isn’t.

Case in point : I submitted the trigonometric operators. In my PR, I followed the examples for the other filters already on the wiki and thus only showed how to use the filter in a filter run. I thought of writing a tutorial to explain how to use that to create graphs like in the demo from @saqimtiaz, but ended up dismissing it fearing that may be to involved for the doc.

In other words, what I’m asking is : Should we aim to “hand-hold” users with detailed step-by-step tutorials, or should the doc aim to explain the most “basic” use-case and let the users figure out for themself how to build up from there ? Is it allowed to link outside showcases ?

Very naive end-user question here : Wouldn’t it make sense to set a limit for a PR based on the estimated reviewing time rather than on the number of tiddlers ?

Maybe a rule of thumb would be to submit changes requiring no longer than 2 minutes to review ?

That would be IMO a great way to reduce friction and would feel much more rewarding. A mention “pending review” could be added as a caution message for new users. Or this could be done wikipedia style, with a “quality” flair added on great articles, which would have the added benefit of providing good examples for contributors to follow.

Github already provide RSS feeds, but integrating this to tiddlywiki would be great, especially within the tool to submit PR that @saqimtiaz has created. I have no idea how difficult this would be to implement though.

EDIT: found a bunch of tools for RSS feed & github

3 Likes
#46

I think it’s OK to have some more “How to” instructions for complex functions.

I did create an “interactive HowTo:” How to create dynamic editor toolbar buttons which contains several buttons that the user can click.

It allows users to create a new editor toolbar button and a matching keyboard shortcut.

Creating something like this is complex and if there is a typo somewhere it won’t work. …

So clicking some buttons, which create a working result imo goes a long way.

1 Like
#47

TBH, I think that is (at least) one major heart of the issue. Another way of saying that is: documentation for whom? The vast richness of TW is a conundrum in knowing how to document it. Just FYI, I’m not sure at all.

On the one hand the terse method (brief, summarised, developer fit) is to the point.

On the other hand, the long ramble, illustrating usage with extensive “hand-holding” examples is very much more end-user embracing.

What I would say is only one thing. Trying to do both at the same time requires extraordinary writing skills.

Just a comment
TT

1 Like
#48

From the end-user perspective, certainly, but lines or files can be enforced automatically by a gate that won’t allow the PR to deploy unless it passes, while review time can’t. My goal with the criteria is to make everyone (including me) comfortable that it’ll be robust against users who aren’t always doing everything right.

IMO 2 minutes is a little too short, but (and this is another problem) it does depend on how thoroughly people would want to study the changes.

#49

To tweak existing, or add new features/functionality (say filter operators, for example) should involve a standard library of reusable samples to test those tweaks/additions.

Working examples of features/functionality should come from the very standard library of reusable samples.

There should never be a need to create anything that is solely for the purpose of examples in documentation.

Code something once and make it multi-purpose.

If there is a standard library of samples for proper testing of tweaks/additions for future versions of TiddlyWiki, those samples should be available in TiddlyWiki documentation for users to learn from.

If there is no such standard library of samples, then I have reason to be concerned about the whole software development process re TiddlyWiki.

I have a philosophy regarding software development: document first, then test the documentation. Then create test cases/scenarios, and then test them. Then code.

When the software product is ready to be released, you have not only the documentation proper, but also working code examples from the test cases.

Coding everything, then asking for help with documentation and working code samples after the fact? That is arse-backwards.

If some folk agree on a new feature for TiddlyWiki, create a group and a forum for that. Work on documentation first. Then test cases/scenarios. Then code.

If you can’t start by properly documenting it and creating test cases/scenarios/use-cases for it, should you really be building it? If you build it without those first steps, you get what you get. And continuing that pattern and expecting different results: insanity.

The people, developers and the community (complainers and otherwise) aren’t shoddy.

The complaints, dollars to doughnuts, are a symptom of a shoddy process, and the lack of a proper system to support a proper process.

#50

@Charlie_Veniot there is a lot of wisdom in your words although perhaps it needs to be modified for tiddlywiki given most developers are volenteers and may not be able to see such methods through.

We do need to lift some work off the shoulders of developers but as I have pointed out in some cases we need just a little more so that we, the rest of us, can run with. I think that is clear from your suggestions we cant drop the ball yalfeay through.

Perhaps you / we can weave into your suggestions ways to destribute actions without too much complexity.

#51

All,

Tiddlywiki already has features to support documentation such as the difference preview and on import. The ability to detect and package changes.

Perhaps if all documentation tiddlers had shadow tiddlers then anyone could make document improvements on tiddlywiki generating a json of changes and submit them to the document discussion where others can drop on tiddlywiki.com and review.

Once done this package can be used to generate changes into git hub by a qualified contributor. This contributor needs to do a final but not exhastive review as others would have already.

It can be hard to reach consensus in a community but let us just try this adding in the great ideas of our community as we go.

1 Like
#52

Well, that will be the extent of my contribution, I think.

I believe TiddlyWiki ought to have a proper website built with a proper CMS. Although I’m a believer in eating my own dog food, I won’t eat it until it is ready.

Because of unorthodox views, I am finding myself less interested in sharing them.

Besides, it may just be my cognitive challenges with TiddlyTalk (that and/or the kinds of discussions going on here), but I’m finding the community more work and less fun lately. So I’m not much in a mood to contribute or otherwise participate.

So I find myself wanting to go off and spend time on other things that get my mojo going.

Maybe I’ll contribute via diving into my way too many TiddlyWiki projects, or (really interesting to me) prototyping the kind of TiddlyWiki site I’d like to see (easier for me to show what I mean than explain it.)

Or detach completely and dive into a crazy project: create my own Wiki software with, of all things, QB64. Just to scratch a major programming itch with a really meaty project.

I’d suggest folk forget about big projects. Go little projects. For example: start gathering sample code into a repository that is useful for both testing TiddlyWiki and as documentation for users. Two birds with one stone.

1 Like
#53

Here is an example JSON, download and drop on tiddlywiki.com keep the import tiddler open so you can visit each of the tiddlers. Note how one of the tiddlers contains a macro and belongs to a different package; Perhaps this should be submitted separately or is there already an alternative I have missed?

Example-improve-message-examples.json (3.1 KB)

[Edit] Actually there are sufficient features in the Import process to review how it looks, what the changes are “differences” before import. Once imported keep the list of imported tiddlers and visit each.

Either the same person or someone with GitHiub permissions and knowledge can do the same and then;

  • hit edit and edit this tiddler on GitHub

Things to be resolved

  • When you add a new tiddler the “edit on GitHub method is not available”

  • If your change a core tiddler this is not valid, perhaps a good thing, but a similar version of empty with github submissions would be nice.

  • Not delay is helpful, if one needs to submit a change that subsequent ones are dependant on but may have a negative impact. Consider my package one tiddler belongs elsewhere but the others depend on it.

  • You will see however that the GitHub version is in raw tiddler format, and one will then need to identify the differences to update it. What I suggest is a button that can copy the whole of the modified tiddler in this raw format, that can be pasted directly into the Git Hub tiddler.

  • Git hub will I believe separate the differences (although I am not sure what determines the field order).

2 Likes
#54

@TW_Tones, good work making things concrete with specific, easy-to-check improvements

I’m not sure the answer to this. If the new macro is needed, another question is whether it should be added to the already existing tiddler: $:/editions/tw5.com/wikitext-macros.

Also, keep the import tiddler open and change the preview type to diff and then expand each tiddlers to see the differences. No shadow tiddler requirements for that approach.

And it might be better to drop the tiddler on Saq’s PR maker wiki. Tiddlers imported there are automatically added to the pull request (nice work, @saqimtiaz!). After that, creating the PR is a matter of just filling in the PR title and description. I think most of your “things to be resolved” don’t apply to Saq’s wiki.

Your proposed changes add several examples and as they stand are clear improvements. I think the changes would be even better if they are fully functional.

To make this one functional, for example, it needs to be wrapped by the fieldmangler widget:

This example uses the message in the ButtonWidget:
<$macrocall $name='wikitext-example-without-html'
src='<$button message="tm-add-field" param="fieldname">add "fieldname"</$button>'/>

That way when the button is clicked, the field will actually get added to the tiddler.

And if you made the other examples fully functional, you could just use the existing wikitext-example-without-html for all of them and not need to worry about introducing a new macro.

1 Like
#55

My second example is the code for the action send message widget for copy and use and is not executable stand alone hence the different presentation.

Messages are strait forward with few parameters. I am keen to add examples to other widgets for different overall forms especialy when there are a lot of parrameters some of which are incompatible.

#56

A post was split to a new topic: Kickstarting the Documentation team

#57

A post was split to a new topic: Suggested flow for getting started with improving documentation

#58

Testing and documenting your changes is part of being a developer and it’s part of doing a good job on any change you make. Nor would TiddlyWiki be making unusual demands here compared to other open-source projects. This is really not a big ask. And this is coming from someone who just explained how hard it was to start contributing.

Yes, adding docs and tests could make it take longer to finish. That’s fine with me, because when it is ready, we actually know it works and everyone else knows how to use it. Maybe it even sits for a few months in the meantime. If that’s really what’s stopping you from publishing something important, then you can always send up a PR and say you aren’t going to have a chance to document and test it soon and would someone else mind taking a whirl at it.

2 Likes
#59

2 posts were merged into an existing topic: Suggested flow for getting started with improving documentation