[TW5] Documentation Proposal (Improved Examples)

[TonyM]

Folks,

I plan to start contributing to the TiddlyWiki documentation. I want to spell out what I am keen to add, so wanted to open it for discussion before hand.

Please keep this discussion focused on what I propose if possible.

As my Newbie status fades I am still finding the documentation falls short of my needs, I would like to add to the documentation with everyone's help the following;

• Examples (need not include "Try It")
  
• Provide full examples with the full statement eg using list or list-links to demonstrate a filter
• So it can be copy and pasted into someones wiki
• Provide examples with placeholders for the major forms of a command
• The alternatives where a command has distinct applications
• Allowing copy, paste and edit.
• Provide examples where values are pulled from the current tiddler
• Too many examples only have static tiddler names or literal strings
• When building reusable macros and solutions we need examples of how to extract values from the current tiddlers title, fields and tags.

I believe such examples will support newbie and expert alike and act as a more practical reference. Of importance it will help people get over the syntax and references humps TW5 presents, and make it easier to learn by example.

If people smarter than me can bring together all the ways and standards for references and transclusion into a single reference tiddler as well would be helpful as currently the different forms are all over the place.

Are there any other critical pieces of info needed?

What do you think?

[Riz]

If someone could also extend the dev docs, that would be wonderful too. As it is now, it gives a broad outline of practices in TW. Beyond that we are expected to understand the use cases and best practices by looking at the core tiddlers. I think if we manage a couple of more stepping stones, the relatively new ones to programming might build something useful to themselves and community.

Oh, also a suggestion to add a separate tab in the community tiddlers edition for plugins alone, preferably in a table format giving link, author, and a one line description.

One other thing I strongly feel should be done is re-ordering the topics on the tiddlywiki.com sidebar. I guess some logic has gone into organising it like that, however I fail to grasp it. Under the topic "Learning", we have topics like "Creating substories" coming before far more basic things like "How to add a new tab to the sidebar". You would think that "editing with emacs" and "editing with vim" will be close to each other, but nope. And to cap it all, the first step - "Creating and editing tiddlers" comes way down -somewhere in the middle.

I understand the possible counter-argument to this is that TW5 is a hypertext based wiki and table of contents is not the main method of organization. However, to someone new to wiki, it is a confusing quagmire. It was to me while I started, and my learning process has been extremely inefficient and time consuming. I have a feeling that I am not alone in such a situation.

Last but not least, little less dull colors, please.

[@TiddlyTweeter]

Ciao TonyM

I'm replying here from a particular perspective. One of the Reluctant Crap "Forced" Programmer. I like what TW can do. I loathe having to fiddle around trying to get something done (one way around this would be to have a route to pay people to do it for me--but that is another issue).

I'm perhaps in a small minority that is seriously cognitively challenged by procedural computer logic. I find the documentation at tiddlywiki.com tantalizingly suggestive. And then I'm lost for a while.

The FIRST thing that would help me is a few fully-worked though EXAMPLES based on working towards an explicit final functional USAGE aim (e.g. "How to write, index and print a cookbook" or "Ways to create a photo album for grannie"). Material, real, implemented solutions documented in detail would illustrate things  in a way that suits my learning style. I'm not sure whether others have my problem so extreme.

A SECOND thing that would help me is CRIB SHEETS--i.e. succinct overviews of functions with fuller example sets. Some of the things Tobias Beer authored along those lines (like is stuff on filters) are excellent, though beginning to age now.

Best wishes
Josiah

[Diego Mesa]

Hey Tony,

Is there somewhere I can "subscribe" or follow your efforts on this front? I am 100% behind this! 

Diego

[Ed]

Hi TonyM,

Sounds good to me. Great that you want to do that.

Now I do not know what Eric Shulman would think and I can not speak for him,
but recently I looked at his effort of making an TiddlyWiki course and that looked
impressive. Might there be a way that you two could cooperate?
À la prochaine, Ed.
.
.

Op dinsdag 28 november 2017 23:40:51 UTC+1 schreef TonyM:

[TonyM]

Diego/Ed/Josiah ,

I think this thread is the only place to subscribe at this point. In my view we need to hear from a few others who have or can help integrate such documents with the tiddlywiki effort as  a whole, it is best not to step on each others toes, however such waiting is often the death of such projects, so we must proceed regardless. As Ed points out Eric should really provide some guidance if possible, after all it is often he who produces answers of the quality we need, not to mention other individuals in the forum. Jeremy as well should chime in. 

I also think key to this is using the proper method to contribute to the documentation, I have not worked out how to do this yet or we could use a separate shared user environment like a mediawiki with references to tiddlywiki.com. where we can build a single point of truth and all contributors can edit. The pain with MediaWiki is its a second markup, but it also has talk, and revisions etc...

We just need to pick an appropriate way towards our goal even if we shift latter and get started now.

Josiah, I think what you ask for will come after the fundamentals I raise are dealt with, or at least once started. For example if someone is providing instructions on how to  "How to write, index and print a cookbook" if they can say we use the list widget of the form documented here, and customised as below we then blah blah, the effort of writing such solutions should be much easier and the solution knowledge base grows on top of a knowledge base of the elements. The elements can be improved and expanded without revision in all the different solutions like Grannies photo album.

If there is no movement on this and no clear objections I can open a Yammer network for conversations and place a Dedicated MediaWiki online to start moving forward. I have no interest in supplanting existing forums etc.... only promoting a focused project to ease our own and others path to tiddlywiki adoption and excellence. In fact as we build more supporting doco we can post it here for review.

Regards

Tony

[Diego Mesa]

Hey Tony,

I wonder if we should ask Jeremy to let us use 

• tiddlywiki.com/dev-docs
  
• dev.tiddlywiki.com
  
• etc.
  

That way we are actually using a tiddlywiki on GitHub. I assume that would be easiest for merging the docs back into the actual tiddlywiki.com. If we cant use that, then the github repository itself has a "wiki" feature we could work off of.

[@TiddlyTweeter]

Ciao TonyM

Three points ...

1 - I do NOT encourage you to open any other forum. Not because I don't think its a good idea but simply because all attempts I seen like that have largely failed so far. The fundamental fact is there are not that many people here. We are a finite number. Though, when it comes to actual writing it could have a place though, but only once its moving. My 2 cents.

2 - Regarding the more expansive descriptive documentation I was talking about I'm not sure that is TW core material. I was talking about TW tutorials. I think they can exist on their own. Its more about linkage (see 3).

3 - Our BIG problem on GG is FINDING stuff. Its not as if people didn't already give heart to explanation. They do. And it gets lost. Daily. I think that is part of the issue. A big part of it.

Best wishes
Josiah

[TonyM]

Thanks for your contribution Josiah,

On your response to item 1 I agree in principal but if no one starts to act and say 5 of us worked together in a side Forum posting end product here I see no problem there.

On 2 we can start work on side doco now and petition to have it referenced from tiddlywiki.com

On 3 I read almost anything here in last 3 months and more as a results of specific searches and I am building my own reference materials and often link to relavent discussions. I harvest info from the forum and will use this info for any doco I contribute to, however the more I learn the easier it is to curate and I often see short cuts to learning tiddlywiki.

Also

In addition to specific details we need peer reviewed conceptual outlines. What follows is part of draft work in progress to illustrate my point.

If you stop to think about it, in tiddlywiki, everthing references almost everything and any change is reflected almost everywhere and instantaniously. These updates occur with any change at all, at least anything you can see, any new item you look at will update when you open it. keep in mind a simple click can be enough to make a change stored behind the sceens.

since tiddlywiki is always upto date, you could say it does everthing just in time (for you to look at it). its just in time for every relavant context as well. until everything is rendered for you to see it, you can not do anything. this is why sometimes you just have to wait. its the price we pay for everything to be up todate. this just in time method in someways prohibits batch processes, you could say its not procedural but contextual and just in time.

With few exceptions if any. all changes come from the user, and when they do everything that must be changed is and rendered in the new context. this seems to be the essence of event driven processes that keep all objects and their attributes upto date just in time.

Of course there are differences when you actualy change something vs just changing your view or context.

The above account in someways explains why i did not initialy understand why you need buttons and similar to trigger any action because tiddlywiki waits until you change something including pressing a button before it acts, reevaluates the context, updates everythin it must and renders it just in time.

this model will not nessasarily be a supprise to anyone who is a webdevloper, object and event driven coder, and strangly anyone who coded online transaction based mainframes. it can however take someone with advanced proceedural languages and batch programming time to grasp,

this structure also sheds light on tiddlywiki not responding naturaly to multi user updates, though fine with multiuser read only.

End of example conceptual outline.

[Alex Hough]

Hi,

a suggestion made elsewhere on this group (by me)

Build on top of the latest pre-release. Document your play. Then when the pre-release is released collect the play and documentation into an accompanying TiddlyZine.

best

Alex

--
You received this message because you are subscribed to the Google Groups "TiddlyWiki" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tiddlywiki+unsubscribe@googlegroups.com.
To post to this group, send email to tiddl...@googlegroups.com.
Visit this group at https://groups.google.com/group/tiddlywiki.
To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/f3726758-6a72-4612-9fe7-d36717f6bfcd%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

[@TiddlyTweeter]

Ciao Alex, TonyM & all

AlexHough wrote:

Build on top of the latest pre-release. Document your play. Then when the pre-release is released collect the play and documentation into an accompanying TiddlyZine.

Small, slightly quibbling, footnote to Alex: I don't understand why you connect it to following pre-releases only. IMO the idea is a good one applied to all and any edition.

TonyM wrote:
... the more I learn the easier it is to curate and I often see short cuts to learning tiddlywiki.

Right. Its public decent indexing that is missing.

Whatever the downsides of flagging materials not primarily designed to be documentation I still think its of great merit.

I learned more from reading GG than anything else.

My issue is I often can't locate something again when I recall it later and want to find it. It becomes a burdensome, inefficient and often failing process.

I guess the big problem is the scale of WORK involved in providing a decent index that points to relevant but ONLY relevant materials in GG. I doubt its sustainable for more than a few themes since the medium itself works against it.

---

I DO think it might be interesting through GG to pursue the development of a Specific Defined Application (i.e. a Use Case)  being explicit on aims AND that one is also trying to document the process.

WHY is this attractive? Because its "business as normal" just with a tweak of thoroughness. I personally prefer solutions that can add documentation with the most minimal overhead. (I'm thinking here of stuff that could form "Tutorials").

That may be workable. And I think it has a higher chance that others will contribute because the weight on them is minimal.

Just thoughts.

Best wishes
Josiah
 

[ste...@gmail.com]

Just chiming in to point out that this sounds like a very good idea. Improved, copy-and-pasteable examples would be a huge step forward. Oftentimes I read an explanation on www.tiddlywiki.com, don't quite grasp it, but wonder how much easier this might be if there was a fully usable example.

I also like the sample conceptual outline above.

Cheers,

Stef

[TonyM]

Alex,

I saw you post before about the idea of a tiddlyzine, it sounds interesting but I personally do not have a depth of understanding on this, could you outline the idea of a TiddlyZine?

The trick I think is to collect contributors or lift content from Google Groups and post in a dedicated blog, with a periodical subscription to posts available. This requires a small team to avoid tiying one person to a millstone.

Tell use more, about your vision.

Tony

On Monday, 11 December 2017 00:00:14 UTC+11, AlexHough wrote:

Hi,

a suggestion made elsewhere on this group (by me)

Build on top of the latest pre-release. Document your play. Then when the pre-release is released collect the play and documentation into an accompanying TiddlyZine.

best

Alex

On 10 December 2017 at 01:42, TonyM <anthony...@gmail.com> wrote:

Thanks for your contribution Josiah,

On your response to item 1 I agree in principal but if no one starts to act and say 5 of us worked together in a side Forum posting end product here I see no problem there.

On 2 we can start work on side doco now and petition to have it referenced from tiddlywiki.com

On 3 I read almost anything here in last 3 months and more as a results of specific searches and I am building my own reference materials and often link to relavent discussions. I harvest info from the forum and will use this info for any doco I contribute to, however the more I learn the easier it is to curate and I often see short cuts to learning tiddlywiki.

Also

In addition to specific details we need peer reviewed conceptual outlines. What follows is part of draft work in progress to illustrate my point.

If you stop to think about it, in tiddlywiki, everthing references almost everything and any change is reflected almost everywhere and instantaniously. These updates occur with any change at all, at least anything you can see, any new item you look at will update when you open it. keep in mind a simple click can be enough to make a change stored behind the sceens.

since tiddlywiki is always upto date, you could say it does everthing just in time (for you to look at it). its just in time for every relavant context as well. until everything is rendered for you to see it, you can not do anything. this is why sometimes you just have to wait. its the price we pay for everything to be up todate. this just in time method in someways prohibits batch processes, you could say its not procedural but contextual and just in time.

With few exceptions if any. all changes come from the user, and when they do everything that must be changed is and rendered in the new context. this seems to be the essence of event driven processes that keep all objects and their attributes upto date just in time.

Of course there are differences when you actualy change something vs just changing your view or context.

The above account in someways explains why i did not initialy understand why you need buttons and similar to trigger any action because tiddlywiki waits until you change something including pressing a button before it acts, reevaluates the context, updates everythin it must and renders it just in time.

this model will not nessasarily be a supprise to anyone who is a webdevloper, object and event driven coder, and strangly anyone who coded online transaction based mainframes. it can however take someone with advanced proceedural languages and batch programming time to grasp,

this structure also sheds light on tiddlywiki not responding naturaly to multi user updates, though fine with multiuser read only.

End of example conceptual outline.

--
You received this message because you are subscribed to the Google Groups "TiddlyWiki" group.

To unsubscribe from this group and stop receiving emails from it, send an email to tiddlywiki+...@googlegroups.com.

To post to this group, send email to tiddl...@googlegroups.com.
Visit this group at https://groups.google.com/group/tiddlywiki.

[Mat]

TonyM, to save you time I'll say this:

Expecting people to go to some other web-address, be it to some forum or a wiki, will not work. All attempts have failed, and there have been many over the past 10+ years. IMO people go here and to tiddlywiki.com. 

The most promising strategy I can think of is something that works from within the users own TW. That way it is always accessible and it is probably right there when the issue comes up.

The optimal solution would be TWederation which I will not describe here but which has been extensively discussed... and promoted as a solution to documentation and much more.

Another, less ambitious idea could be a TW-plugin that lets the user access and participate in a semi-public folder on someones Google Drive or similar.

For example, the plugin could(!) be a single tiddler showing:

* a simple iframe showing a shared Google Docs folder. 

* a button that creates new tiddlers from a template. This shows (in view mode) a link-field where the user inserts the url to an actual google document. Below this is an iframe that shows this document. And this tiddler is tagged e.g "doc".

* the plugin tiddler with the iframe also has a list of all tiddlers tagged "docs"

The user-inserted url is either to a shared google doc in his/her personal account or it is to one of the docs found in that shared folder. Sharing your own google doc requires a google account but reading and editing(!) a public document does NOT require a google account!!!

One more thing:

ANY solution that is not part of the standard TW distro or at least prominently advertised on tiddlywiki.com must be actively promoted! By "prominently advertised" I mean permanently seen in the default tiddlers! - not hidden among the other user contributions. So if not prominently advertised, it would have to be brought up again and again here in the GG. The powerful advantage with the plugin idea (or TWederation) is that it is within the users own TW so once you have, you have it. The promo is then about new people getting the plugin which is probably even a bit fun.

<:-)

[TonyM]

Mat,

I made a point of not wanting to step on each others toes, and I want to ensure this.

My view is that improved documentation needs to be produced and added to TiddlyWiki.com, and where not practical references from tiddlywiki.com. There is no harm building and collating this elsewhere, especially with a team

Any suggestion of another address/collaboration tool is a workplace or team effort, and unlike all the historical failures to which you refer, I am not trying to replace or supplant anything. In fact I would propose we do our best to integrate with tiddlywiki.com and reference the Google Groups as much as possible.

Your ideas about Visible within peoples wikis, TWFederation etc... all sounds promising, but until someone makes these a reality, with respect they are thought bubbles. Can you help us realise this?. I for one get thoroughly confused researching TWFederation etc... Even just the Git hub documentation contribution method is confusing, for someone who does not currently use GitHub other than as a source.

Your suggestion of google drive seems no less complex or fiddly so please refine this and make a proposal.

It is really clear we are an informal community , all with different ideas, skills and experience planning a solution for ourselves and others with different ideas, skills and experience. The result is a complex mess of indecision.

No solution is forever, and none perfect. They will come and go over time and as long as they can contribute something of value to the community they will be worthwhile. So far however we have analysis paralysis, or too many competing options to proceed.

In my community and professional life I have come across a number of occasions where similar circumstances have arisen. The only time I have seen progress is when someone bytes the bullet (often me) and jumps in the deep end and they gain supporters. From when I was young, living in Papua New Guinea, New Zealand and Australia, I came to learn that once my frustration with group indecision reaches a certain level,  I tend to step in and start leading a solution, even if it is not perfect, its better than little or no progress. One of these things can happen;

1. People get on-board, it gets rolling and then we adjust our target based on what we learn and get wonderful results.
2. I spend a lot of time and effort, listening, supporting and solving problems but it goes to waste because no one gets on board
1. Because people nit pick because the solution is not perfect or in their image
2. Because another solution, comes along, often inspired by my effort and is duly adopted with success.

If no one acts Nothing happens, often because we wait for someone else's better solution.

Now here is my personal circumstance as background and by way of explanation how I relate to tiddlywiki

1. I am a 50 something ICT Professional of 30+ Years with a broad experience in many ICT disciplines, Of particular relevance recently, collaboration and Knowledge Management
   
2. I was retrenched from my second high-paying corporate job in as many decades
   
3. Being sick of the corporate world and my inability to use all my skills I have started my own Business https://PSaT.com.au
   
4. I see TiddlyWiki as a key enabler for personal, Business and client solutions
5. I am committed to TiddlyWiki in a personal, community and professional capacity
6. I need to earn a wage, and there is a risk tiddlywiki will crowd out real paid work, however I am committed to building my own deep understanding and references for tiddlywiki
7. If I am going to the effort of building my TiddlyWiki knowledge I would like to share that knowledge
8. At present, There is no easy avenue beyond publishing solutions and posting in Google Groups for me to Give back to the community.

The community will get a lot from me, and I am sure many others, like yourself already give as much as they can. The problem is if it costs us too much effort contributing, we contribute less and some people run away from contributing. I want to have this fixed for us all.

Mat, I respect you contribution to the community as a whole, and to this particular subject but can you help us get over the hump?

Tony

[@TiddlyTweeter]

Ciao TonyM

Your thread is causing me to think.

I'm feeling its really beginning to register the problem with documentation in a more move-on-able way.

A few comments. To support your overview and mark a few places that maybe don't get so easily noticed ... more sociology of behaviour than a solution ... but I think worth pause--even though I'm partly repeating myself.

1 -- Users often GET documentation by asking questions on GG. --> The "documentation" and solution finding are strongly inter-woven.

2 -- BECAUSE Google Groups loses its own history very quickly into a swamp of "difficult-to-find" --> its very difficult for both BEGINNERS and folk not reading everything everyday to find relevant answers already there. And even if you are reading, if you are not cataloguing, its a struggle often to find the "80% there already" solution. There is a big ORIENTATION problem from lack of indices.

3 -- Since solution finding is a honing into PRECISE ANSWERS there is a slight tension between Generalising and Specifics ... by which I mean unless you read through several threads about, say, "timing" you may not be able to bring a solution together without extra help. The current discussion of __help needed in making a "n" minute timer macro__ is a good example where there are lots of parts towards a solution that exist ... stuff already made, discussions already done, new thoughts. Yet we all fumble finding the relevant ones efficiently.

I think an issue is definitely around documenting AND linking to some key themes that will reduce the amount of repeated RE-CREATION OF 80% OF THE WHEEL.

[Jeremy Ruston]

Thanks everyone for the interesting thread — and particularly to Tony for stepping up to the gargantuan task of improving the documentation.

Tony’s original post makes a strong point very well: that the documentation would be more useful with more examples. It’s a great observation, because inserting examples into the existing docs can be done without necessarily having to do the kind of major refactorings that we’re already considering elsewhere.

However, we’ve now gone on to cover much more familiar ground about the methods and tools that we should use. The first thing to note is that there is already a dedicated Google Group for discussing documentation improvements:

https://groups.google.com/group/tiddlywikidocs

In terms of spinning up a new wiki for working on the documentation, I’m not convinced that a single shared wiki will serve our purposes. What if, for example, while one person is working on reorganising content in one way somebody else wants to experiment with reorganising content in a different way.

I think that what may be needed is more like the way Git works: the ability for any individual, or group of individuals, to fork the documentation and make their own changes to it for consideration for merging back. The easiest way to achieve that right now is to download tiddlywiki.com and upload it to tiddlyspot.com, and then make edits. It’s easy enough for me or another GitHubber to download the changes and compare them to the original. As Mat suggests, federation might offer more sophisticated ways of doing basically the same thing.

Best wishes

Jeremy

--
You received this message because you are subscribed to the Google Groups "TiddlyWiki" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tiddlywiki+...@googlegroups.com.
To post to this group, send email to tiddl...@googlegroups.com.
Visit this group at https://groups.google.com/group/tiddlywiki.

To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/81f45cdb-aad2-450b-9b76-dec7f928c436%40googlegroups.com.

[Mat]

@Jeremy and @TonyM

Jeremy, in another thread you wrote out some of the standards you had use to correct a doc-contribution I made.

These are no doubt high standards and the result looks great  - but few can live up to these standards. It's a double edged sword.

It sparks an idea - or maybe it's what Tony has been talking about; It would be useful with an unofficial but still publicly viewable subdomain - like http://unofficial.tiddlywiki.com for "potential docs" and finge stuff that is not suitable for the main wiki! If possible, with a github organization, separate from the main one, with its own Issue and PR boards so it doesn't burden Jeremy. Is that even theoretically possible?

  <:-)

[TonyM]

Mat,

If those with more experience than me think Git is a useful way to do it, we need simplified documentation on how to use git to do this. Most people are unlikely to be experienced with Git unless they code in teams. 

Personally I would be happy to build a series of tools to collaborate collate documentation info which is destined to be published by the proposed method. The team can harvest info from Google Groups, clarify and enhance, cross reference then publish.

If I were doing it I would build a WordPress membership site, Wiki Media instance, Yammer forum or more to discuss the details or similar.

Despite my experience, I have not being able to progress on GitHub this myself.

Regards

Tony

[Mat]

Personally I would be happy to build a series of tools to collaborate collate documentation info which is destined to be published by the proposed method. The team can harvest info from Google Groups, clarify and enhance, cross reference then publish.

I feel I am much too pessimistic to comment on this. But I sincerely hope you get it to work! :-)

<:-)

[Furicle]

Perhaps the first document that needs to be created is the one detailing how to help with the documentation  :-)

But creating a different wiki to document this one seems humorous, if nothing else...

Tony, can you be more specific about your issues with Git/Github?  Do you think the flow won't work? or are there specific steps that need to be clearer?

And do you see this as a 'stand alone' wiki or will it end up as part of tiddlywiki.com ?

[BenTremblay]

Nice to see new energy! It's been painful to watch as 80/20 mediocrity has quenched / stiffled so many innitiative. (I used to use Technorati to spider certain topics / key words as a way of surveying / exploring / discovering new blogs. It's like a memory from some long gone golden age.)

fair winds / following seas!
--ben

[TonyM]

Furicle,

The following is still open for discussion, my thoughts?

• Any additional wiki or website would primarily be about the process of collecting and developing content to be formally posted elsewhere. No in itself a comprehensive wiki
  
• Perhaps a rule should be this (Site/WIki/Project)  is not where you ask for solutions, search if you want, but use official doco and Google Groups to ask questions. 
  
• It should be dripping with links and references to the Formal and tried documentation. Google Groups is not (always) doing this.
  
• It should reference discussions and plugins mentioned in Google Groups, TiddlyWiki.com  does not do this.
  
• It could stand along side the other platforms for example when users curate and extract content from Google Groups and place it in preparation for examples to place in the doco,
  
• It could eliminate superseded content, and chit chat and of topic items from some discussions (Neither Google Groups or TiddlyWiki.com do this)
  
• However much will be refined and rather than discard what we do not use it may as well document other contributions.
  
• If someone works through a long Goggle Groups Discussion they could post a link to a summary in the proposed project repositories, and where the formal documents are.
  

Re: Git/Git Hub, Where do I start? Can you imagine someone naive about it?, there is a lot of lingo, and very little documentation targeting the tiddlywiki use of Git/Hub for newbies. 

I am a ICT professional of 30 years who has not used it, what about the millennial or mum/dad user? I do not even understand the flow to critique it. These are all barriers to wholesale adoption/contribution. 

Lets adequately document it for newbies or just leave it to select people.

Whilst the discussed solution may stand alone and have its own value, it's primary purpose is to collate and feed documentation and training / learning materials.

Regards

Tony

[TonyM]

This looks like a good Solution for Edit Contributions, to specific Tiddlers, Provide a Way to submit tiddlers would help?

http://twaddle.tiddlyspot.com/#Comments%20using%20Google%20Drive%20'Forms'

Regards

Tony

[Mat]

TonyM wrote:

This looks like a good Solution for Edit Contributions, to specific Tiddlers, Provide a Way to submit tiddlers would help?

http://twaddle.tiddlyspot.com/#Comments%20using%20Google%20Drive%20'Forms'

Kawabunga! - please, everyone, let me first make sure it still works. It was a long time ago that I made that and I have not actively followed up with it. It did work well back then but google may have changed things.

Still, Tony, what would the workflow look like then? If it works, I mean.

<:-) 

[moros...@yahoo.com]

Hello everybody,
I just want to let you know that the project who seek to improve the TiddlyWiki documentation structure is not dead. It received green light from Jeremy and others and soon we should have a new docs structure.
Maybe you should take this also into account.
If you want to know more follow the links below:

The GitHub issue page:
https://github.com/Jermolene/TiddlyWiki5/issues/2912#issuecomment-351554436

The demo site:
http://morosanuae.tiddlyspot.com/#TiddlyWiki%20Manual

[TonyM]

Mat,

Thanks for the warning,

Just exploring, I have not worked through the whole idea, but was thinking multiple contributions in wikitext could be submitted, collated, curated then submitted to GitHub.

I would appreciate your ideas, but commenting on any tiddler requiring improved doco is one approach.

Regards
Tony

[TonyM]

Looks great,

We have the desire, the need, the volunteers, a clear image of what we want in the doco and now an improved structure.

Can you explain how we would contribute using got or is that a seperate issue?

Tony

[moros...@yahoo.com]

Are you referring to contributing through GItHub? The new structure is not implemented yet, so you'll have to wait a little bit.

Anyway we need good docs about contributing through GitHub, although some people are afraid of it from what I understand.

This will have it's place in the "Helping the community" chapter (book).

[@TiddlyTweeter]

moros...@yahoo.com wrote:

some people are afraid of it from what I understand.

I don't think we are afraid of it so much as non-comprehending of it.

In my case I can raise a GitHub Issue (with work & a lot more restrain than my usual want). Doing a "PR" (whatever the hell that is) is something totally different that looks seriously weird still to me.

Best wishes
Josiah

[Furicle]

I'm no Git guru, or big GitHub user for that matter.
I do use Git a bit for my sysadmin related scripts at work, some html stuff etc.

Real GitHub people please feel free to step in as needed....

The normal flow with GitHub as I understand it is this:

0 - create a GitHub account
1 - 'Clone' or copy an existing 'repository' or set of code and it's historical info into your own account.
2 - (optional) create a 'branch' where you'll work on one concept or feature you want to improve
3 - make the changes you want
4 - go back to the original repository and create a 'pull request' - you're telling the repository owner you've done something they should add back into the master set of code.
5 - discussion takes place on the comments around pull request
6 - revise changes
7 - create new pull request(?)
8 - project owner(s) merge
9 - repeat at step 2

I'm a little hazy how you keep your clone up to date with the master, and the best way to revise pull requests.

Did that help or hurt?

[Furicle]

Perhaps this is better - the official docs

https://help.github.com/articles/github-flow/

and for an 'illustrated' version of that

https://guides.github.com/introduction/flow/


I can see where that's pretty intimidating for someone not used to the tools...

[Dave Gifford - http://www.giffmex.org/]

This explanation was very helpful to me. I kind of thought of clones and branches as altering a timeline in a sci fi movie, where it never goes back to the original timeline again, and gets orphaned. Now I understand it is about branching off, editing, and suggesting adding the change to the original.

[Diego Mesa]

I have always had used the following interactive tutorials to teach git:

• https://learngitbranching.js.org/
  
• https://try.github.io/levels/1/challenges/1
  

[TonyM]

Folks,

Thanks to the Git Reference materials. 

I have collated all Git Usage References below

I will use these to discover how to submit Doco updates via Git and See if it is suitable for a wider audience, 

Please share your own experience with Git.

[Diego Mesa]

Just to revive this, I'll share a short Tiddler I've been keeping with some great explanations by Eric Shulman recently (attached).

It clarifies the use of < vs <<  amd { vs {{ in and out of filters, and has been very helpful to me.

Im not sure where something like this would go in the current documentation (if it was improved). I always thought it would be helpful to have a Beginner FAQ and Intermediate FAQ.

Best,
Diego

[Igor Guida]

TonyM,

I agree with you.

I'd like to say thank you to @Jeremy Ruston for the amazing work he did with Tiddlywiky that I love, but I never seen before a so difficult project to find doc for.

It's not clear where to found it and if you find something, probably it's not up to date.

Igor