Suggested flow for getting started with improving documentation

Community Projects Documentation
#1

Wow. I woke at 05:00 and ended up here at 06:34 :scream:

@saqimtiaz Don’t ever think your input across the TW spectrum goes unnoticed/unappreciated. Your stamp, your fingerprints on stuff stand out a mile, to me. Thank you. :trophy:

@sobjornstad There’s a thesis waiting to be completed back there. Pointed, targeted and wholly correct, IMV. :trophy:

@TW_Tones stepping back and saying what needs saying, as usual. :clap:

@TiddlyTweeter penetrative observations and levity in correct and equal measure, as usual. :clap:

If what I am about to say has already been said, well, tough, I’m just gonna say it. And this, if it isn’t obvious, is my attempt at keeping @sobjornstad in his comfy chair, and making sure something happens:

  1. Contributor Philosophy: Just Write
      – But I need to do a PR!
       – No, you don’t. JUST WRITE!
      – But who’s gonna do the PR?
       – What do you care? JUST WRITE!

  2. Forum Category: documentation

  3. Create a WIKI POST with the same title as a TW.com tiddler –
     – for example, “enlist Operator”
     – Add the text “This post is waiting for contributions”
     – Save

  4. Reply to the above post to start the discussion thread about enlist Operator, perhaps mentioning WHY the topic needs better docs (though the why is generally a given, I think).

  5. ALL USERS: Make contributions to the WIKI POST at top.
     – NOT REQUIRED: mention your change in the discussion thread below, if you think it needs it.
     – Discuss the status of the WIKI POST in the discussion thread beneath.

  6. Choose another TW.com tiddler.

  7. Goto 1

@Contributors:

Never quote the entire WIKI POST in the discussion thread. This will help avoid the problem mentioned by @sobjornstad above, “I still had no idea where it was currently at, so I gave up” – a frequently occurring problem, for me.

@boris If you want to move this to a new topic to give @Mohammad his thread back, GRA.

Request for Help: Documentation/Demo/Working Examples
#2

IMO, this whole discussion should be moved into the Documentation category!

This is a great idea and could work well for adding documentation that is currently missing, and it’s a good plan for starting discussions. But I don’t think it would work so hot for wide-ranging revisions that cross multiple tiddlers.

1 Like
Request for Help: Documentation/Demo/Working Examples
#3

True. However, I addressed that problem (like the PR hurdle) by completely ignoring it.

As I see it, the issue with tw.com is that the examples are presented in the render, only. That practice should stop. :stop_sign: immediately. When a visitor sees something interesting and wonders how it was achieved, “viewing source” on a tiddler provides little to no useful information, the “clever stuff” being wrapped up in macro-ized wikitext that is indecipherable to the casual reader (let alone new users). TW tiddlers should provide immediate, applicable source usable by anyone, novice to expert alike.

So, yes, you make a fair point but only because of where you started from. :wink:

1 Like