Request for Help: Documentation/Demo/Working Examples

[saqimtiaz]

@sobjornstad

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

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.

@sobjornstad

@saqimtiaz

Once in a while documentation improvements from the .org site could be cherrypicked and merged into .com.

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.

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.

@sobjornstad

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.

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.

@sobjornstad

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

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!

@sobjornstad

@saqimtiaz

I think what is really needed to effect meaningful change is for a group of interested people to take the lead on improving the documentation process and overall work on documentation, help facilitate these conversations and try to translate them into something actionable, and direct that eventual work.

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

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.