Tiddly as a knowledge base alternative to Jira and Wikimedia or blogs for software technical deocumentation

[C J]

Hi everybody.

I am Cedric, a French Software developer and I start working in a very small (4 people) team o software developers in a very small company.

Unfortunately the knowledge is neither organized either shared between people who yet work in the same room and I want to start documenting projects and applications while managing updates and versions. 

Knowing that we already have a Jira to manage our project but we cannot afford for a team plan I was looking for a free open source wikimedia like or a home made blog using Wagtail when I discovered Tiddly. 

Do you think that it can be an suitable tool for me?

Best regards.
Cedric J. 

[Finn Lancaster]

Hi Cedric, 

     It’s nice to know that someone else is using tiddlyWiki for software development organization! From my short experience (about a month), I’ve actually found TiddlyWiki to be perfect for this sort of thing. The wide range of plugins available mean that the software is very flexible for anything you need, for example, there are very good code plugins that support web, c, Python, and Java languages. In addition to this, the saving of tiddlyWiki’s is also super easy, you can make a collaborative wiki with just a few minutes by syncing it via GitHub pages. If you have any questions, or need further info on how to do any of these things described, feel free to respond here or email me directly. 

Regards, 

     Finn Lancaster 

     www.finnsoftware.net

     Implementing tiddlyWiki at wiki.finnsoftware.net

--
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 view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/17edcda9-b33b-4a27-a6c6-d6a12aeff5c3n%40googlegroups.com.

[C J]

Thank you for your answer Finn!

Do you find it easy to make a tree file/folder system with tags and hyperlink and and then establish relations between different topics that share or leverage common resources? 
How would you start documenting a three tier web application for example? Is Debian an obstacle?

Cordially

Cedric

[Finn Lancaster]

Cedric, 

I actually found it rather simple to implement a general file system, using the built in tags and referencing. For instance, I tagged five main pages, configured them to open on the startup, and then would link pages that fell under each of these in the text, so that users could open lower-tier files from these higher ones. Although the wiki was just started, meaning that there are very few files, the overall result and look of the wiki stays organized and clean. 

Instead of Debian or a dedicated server, I configured my tiddlyWiki to save directly to github, and then open the github file containing tiddlyWiki (index.html) on page start. The end result of this is that my tiddlyWiki allows anyone to contribute, and then syncs these changes to anyone else that opens the file. If you are set on using a Debian Server, however, I found this article on using Ubuntu Linux, which should be relatively similar  How To Get TiddlyWiki Working On Linux (addictivetips.com). 

[Charlie Veniot]

Bonjour Cedric et bienvenue à la TiddlyWikernité  (fraternité TiddlyWiki?  Pshiuuuuu ... boom.)

I really can't see TiddlyWiki being anything but a great choice for just about anything.  Even if you try it and decide it isn't right for the job, you still have "prototyping" value and likely have the benefit of having better figured out your needs/requirements.

The beauty of TiddlyWiki, to me: it is like a blank canvas.  Don't let yourself get stuck in the mud trying to figure out "structure."  Avoid "structure block"  (like writer's block), and just get to writing.  Let structural needs sprout organically / incrementally / iteratively, and try to keep things easily adaptable with a "componentized" approach.

It might take time to get everything juuuust right, but it will fit you and your crew perfectly.  The option is a "canned" solution with prescriptive "whatever", and then you have to take time for you and your crew to adapt to the solution.  (Yeah, I much prefer adapt a flexible solution to my quirky self.)

Rock'n roll !

[Sylvain Naudin]

Bonjour Cédric,

@Charlie : je valide le jeu de mot ^-^'

No doubt that Mohammad's Shiraz plugin will be useful for you to format the documentation.
https://kookma.github.io/TW-Shiraz/

I don't use it personally, but everyone says good things about it :)

At the office I use my own version (even if it is not perfect) with the styles of Minstyle.io (https://silvyn.github.io/tw-minstyle/).
(it's not a collaborative wiki, just an extension of my brain to document projects).

Sylvain

(if you don't see forum.tiddlywiki.fr, you're welcome !)

[ludwa6]

The UseCase that Cedric has shared falls squarely in the middle of a problem space that TW is very well-suited to solve, i think, and much as i resonate with the ideas shared by Finn and Charlie have shared, what i'm really hungry for is a working example of some solution that solves a UseCase as close as possible to that which the OP here describes. 

Reason i ask is: much as i love wiki for personal KM & productivity management (have used different desktop wikis over many years, and finally settled on TW5 as the best solution for me), every time i have tried to deploy it as a workgroup solution, it has failed to achieve sufficient traction to warrant its continued maintenance. 

My theory of cause about this could be thought of as the flipside of the very coin that makes wiki such a powerful tool for quickly building an extensive knowledge base, and a PERSONAL interface to same: it's fast, it's "InterTWingly," it can (if built on such sound architecture as TW5) accommodate whatever computer language you might be partial to, etc.  Problem is, when it comes to the languages that stand at higher levels up the KM stack -i.e. for naming and tagging and classifying knowledge- we all have different ideas. I guess that's what Rufus Pollock means, @charlie, when he talks about the shift that we'll see in the coming Componentization Revolution, when that 90:10 ratio of Content:Interface will flip around to its mirror image.  With granular content everywhere, interface-building becomes the name of the game.  Question then becomes: how do we make of that interface-building game a really good collaborative one?

SO: seeing as how i'm no good at this, i'd like to know who really is.  To that end: can you please share here, any and all, links to collaborative software documentation projects powered by TW5 that are open for us all to explore?  (read-only, i mean: the only case of wiki open to edits by all that actually works in practice is Wikipedia -and that only by virtue of its army of dedicated editors!)

/walt

[Hans Wobbe]

Thanks for your post.  It resonated with me since its insights are consistent with my experience.  I also appreciate the Rufus Pollack link

Regards,

Hans

[Finn Lancaster]

@ludwa6 does make a point, at least in my opinion. A wiki is most definitely a powerful tool, and tiddlyWiki holds the potential to make a great, modernized version of one. The issue with using tiddlyWiki as a group or team wiki, in my experience, is implementing proper controls. For example, in my collaborative tiddlyWiki at wiki.finnsoftware.net, I’ve removed all traces of control panel, trash button, and anything to find them, including advanced search to prevent users from modifying the “core vitals” of the software. TiddlyWiki was made to be a personal notebook, and hence has not had proper testing (or documentation) at a team level. Anyone attempting to do this will surely face bugs and issues, and the main thing needed to do all of this correctly is patience. 

The second point I will make is questioning to the extent at which Cedric would like to use TiddlyWiki. It is one thing to make a tiddlyWiki hosted on GitHub that displays your changes. It is quite another to make it fully collaborative, even with all the amazing plugins available. I one again would stress the importance of using GitHub Pages over a server to Cedric if he seeks to make the wiki fully collaborative, as at least that has a little bit of testing for this purpose. 

Regards, 

     Finn Lancaster

     Software Developer finnsoftware.net 

     Implementing TiddlyWiki at wiki.finnsoftware.net 

On Sat, Jan 30, 2021 at 7:32 AM Hans Wobbe <hww...@gmail.com> wrote:

ludwa6:

Thanks for you post.  It resonated with me since its insights are consistent with me experience.  I also appreciate the Rufus Pollack link

Regards,

Hans

On Saturday, January 30, 2021 at 5:29:12 AM UTC-5 ludwa6 wrote:

--

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 view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/da6bc24d-6d48-4e17-a3e4-0e4b92d31f53n%40googlegroups.com.

[C J]

Thank you for your answers! 

I am interested in the git synchronisation and the different aforementioned plugins and approaches. I do not know how to do the git sync and I would need an example.

However, I would like to make it collaborative. Ludwa06 and Finn said that it is difficult for a team. 
I do not know GitHub pages. Is it free? We use a private GitLab business account so I am not sure that it would be the solution.

If you could provide me with a recipe to use it like Finn with the implementation of Charlie and Sylvain's ideas I will try it on Monday.

To be honest I will compare it to Notion, Bookstack and Tettra. Knowing that we are a very small company (14 employees including 4 full-time developers) I have to find a free solution while escaping from the messy situation where nobody knows how the guy who is just sitting next to you installs software, runs programs, writes his code and deploys it, etc. 

This situation has consequences: if someone is absent or leaves the company the onboarding is very hard. Last Monday I spend all my time trying to set up a program. Finally, on Tuesday its developer told me that he has a lot of steps to explain to me, that I have to follow to start the applications with many installations.

 This is my case and the reason for what I am looking for a private Wiki.

Best Regards.

Cedric

[Charlie Veniot]

This is a really great thread o' discussion.

Just to follow-up on all of the latest contributions:

Although I've never played with it, I'm pretty sure, for TiddlyWiki team play , you'll want to get your hands on TW5-SingleExecutable by Jed Carty.

And you'll probably want to volunteer a lead "visionary" in the team to act as TiddlyWiki custodian/librarian/evangelist.

I tend to see your project very much like a software development project, but mostly all about gathering requirements and prototyping, all about assessing needs.  (I get right giddy about those activities.  So much fun !!!)

What I have seen in software development, you often have higher up folk who want certain information, and applications get created for staff to enter data with the goal of providing management with the information management needs. 

Staff often wind up in the unenviable position of experiencing use of the system as "extra work", and the system to be used because "somebody said so."   Yuck.

To me, and right out of the gate, any thing created for people to use needs to provide immediate benefit to those people.  It has to be something that isn't "extra work", but rather something that provides value to each one of them.  When you take care of the little dimes, the dollars take care of themselves, in a way.

So whatever the "big goal/purpose", it can be much easier to get there when other "little goals/purposes" are supported first as something that leads to success with the meatier goal.

Now, I have not yet had my first cup of morning coffee.  Please take all of that philosophical mumbo-jumbo of mine with a bucket of salt.

[ludwa6]

Interesting, @finn, your 2nd point, as yours is the first example of TW5 that i have seen which actually enables collaborative editing (albeit in a simple form, and not without some hiccups :-). Though it appears to be in its infancy, i would be interested (as would others here i suspect, it being so relevant to this topic) to hear in a bit more depth about the form(s) of collaboration your site aims to support, since it is not yet very well elaborated in-context.

[C J]

I also would like to add that the backend developer wants to leave the company and that I am new there so the solution that I am looking for should be very easy to set up and use quickly. I hope that Tiddly will be the right one. 

[ludwa6]

@charlie: clearly you speak as one who's been around this loop a good few times already, and your advice about engaging a "lead visionary" (custodian/ librarian/ evangelist) is right-on, IMHO.

Moreover: I think that work you shared in an earlier thread is an awe-inspiring display of mastery over a number of skill-sets that such a project lead would do very well to have, including Information Architecture, Relational Database Modelling, advanced TW5 interface design, etc.

All that being said: what you've built there is (to invoke ESR's immortal metaphor) a Cathedral, not a Bazaar... And i wonder to what extent such an application might serve the needs of users in the context that Cedric describes. 

Bottom line: i think Charlie's closing point is really the clincher: whatever it is that users will actually find helpful (as indicated not by what they say up front, but what they actually do after the fact!) is what will carry the day.  So it is that i've had to swallow the bitter pill of using Google Docs  vs Wiki for collaborative documentation-building so many times already... (just thinking about it makes me wanna puke :-)

/walt

[Charlie Veniot]

Holy moly, I am extremely emotional all of a sudden.

In my 25-year career, unceremoniously terminated last December, I never felt anybody at any level up the chain really had any clue what kind of work I did.  It never mattered much because the job itself was oh-so-gratifying in every possible way, and my occasional celebratory self-pats on the back easily sustained me.

I am not used to having any kind of recognition for "job well done", and definitely not in such a glowing way.  I am stunned, and that is just about the greatest gift anybody has ever given me.  In my French-Acadian way, I'd say the sensation is: "Taberslack! Tcheu moseusse de caresse!".  (i.e. "Wow!  That is some compliment!")

So thank-you, big time.  (I've been busy polishing up my résumé and trying to figure out what I want to be when I grow up.  I must get back to my "ORM-ish à la TiddlyWiki" project.)

All of that aside: I was once told that I "coddled" my users too much.  Well, take care of the little guys in the trenches (i.e. their needs), and you can take that hill.

[Finn Lancaster]

@ludwa6 asked for a bit of explanation of sorts for my wiki site, so here it is: 

Although it is still in its infancy, a fact @ludwa6 pointed out, my wiki seeks to be a collaborative collection of programs people have made, as well as explanations and ideas for new programs and techniques. Right now, there are very few contributions, so I’m mainly trying to advertise/build the site base. It is my hope to build the next Wikipedia for coding: where anyone can add, edit, or share programming ideas, build them, or work with other members to make them. After this, and a few site requests I’ve received, I will probably add a documentation/developer page to the site main at www.finnsoftware.net, but for now upcoming changes are posted at the “Coming Soon!” page. 

To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywiki/86a197a3-05ef-44b7-a70a-0571f3531fb4n%40googlegroups.com.

[PMario]

On Saturday, January 30, 2021 at 2:28:54 PM UTC+1 work.ced...@gmail.com wrote:

I am interested in the git synchronisation and the different aforementioned plugins and approaches. I do not know how to do the git sync and I would need an example.

However, I would like to make it collaborative. Ludwa06 and Finn said that it is difficult for a team. 
I do not know GitHub pages. Is it free?

Yes. BUT I think it only works for _public_ content and I doubt that's what you want.

 

We use a private GitLab business account so I am not sure that it would be the solution.

We (TW) do have a GitLab saver and GitLab also has a "pages" option.

... But if you use GitLab and the CI/CD elements, it will also be possible to dynamically create "parts" or "all" of the wiki content in a "scripted" way. You only would need to "compile" the wiki after a commit is made, or may be if you TAG a software version.

BUT ... This would be the second step of the game.

In the OP you wrote that some of the "maintainers" of the wiki sit in the same room. .. So "locking" the wiki would be simple. Just ask the others to save their wiki, if they are editing it. ... I know that this is far from perfect, but if you are at the same place -- it's simple.

To be honest I will compare it to Notion, Bookstack and Tettra.

I think the only "fair" comparison would be with Bookstack, since it can be "self-hosted" and is open-source. All the others are proprietary products.

But I think you did land here at the TW group, because it can be a "single page" wiki, that can be stored alongside 1 project, with no extra dependencies. For Bookstack, imo you will need your own DevOps person that takes care of the server-side and keep it running.

TiddlyWiki is a single html file, that imo easily can contain the text content needed. ... Images should be "external", but that shouldn't be a big problem with GitLab-pages.

Knowing that we are a very small company (14 employees including 4 full-time developers) I have to find a free solution while escaping from the messy situation where nobody knows how the guy who is just sitting next to you installs software, runs programs, writes his code and deploys it, etc. 

In the OP you wrote, that you use Jira, to manage your code. In the response above you wrote you have a GitLab business account ... So I'm a bit confused. Both software stacks do similar things ...

 

This situation has consequences: if someone is absent or leaves the company the onboarding is very hard. Last Monday I spend all my time trying to set up a program. Finally, on Tuesday its developer told me that he has a lot of steps to explain to me, that I have to follow to start the applications with many installations.

I think that's a perfect match for a TW.

 

 This is my case and the reason for what I am looking for a private Wiki.

As I wrote, it may be possible, to create parts of the wiki automatically, if you use a CI system.

BUT it would need a lot more info, what you really want.

----------

There is 1 question left: ... Is it your idea to create a knowledge base, or does everyone desperately want it. IMO it's important that it's sanctioned from the management.

-mario

[ludwa6]

Given the breadth AND depth of experience being shared here, w/r/t both tech AND social engineering, i am encouraged to think that some viable solution(s) may well emerge for Cedric, maybe even generalisable to other UseCases in other non-software related domains.

For example: i created this site- valedalama.github.io -some months ago as a proof of concept, to test a few propositions:

1. Can i put a site online that will serve a subset of content selected for push from my TiddlyDesktop PIM, with the additional benefits of:
2. Affordances for collaborative design/ discussion/ documentation;
3. Version control & history;
4. Industrial-grade hosting service, with good performance & backup; and
5. Free & Open Source Software, from bottom to top.

What i got with this combo of TW + Github.io ticks all the boxes in principle, but in practice... I would have to say that,  while requirements 3, 4 and 5 are passed with flying colours, req (1) involves a bit of clunky workflow that i could probably automate away -and would do, if i could only engage some players on my team to make this a win on point (2) as well, but sadly this has not happened. I've given colleagues the option to either (a) use Github affordances for issue-tracking and/or discussion; (b) edit individual tiddlers to merge via pull-request, or else (c) just download index.html, edit in your browser and email back to me, but it seems these are all a step too far to ask.  

Of course: this little proof-of-concept doesn't yet hold a lot of USEFUL content (maybe your situation as well, @finn?)... and it IS perhaps too much to ask of people who work primarily in the field and not online.  Yet they do seem to love their Google Docs, so... go figure! 

Still, i have to wonder: given the hooks of which PMario speaks, which Finn seems to be using to some extent, surely there must be other TW sites out there in Github.io and/or GitLab land that we might look to for some insight -yes?

/walt

[ludwa6]

Hey @charlie: you may have lost a job, but i suspect your career is far from over.  Tell ya what, mate: if you could tweak that ORM-ish TiddlyWiki in such a way that users of your system documentation could easily contribute edits or even comments-in-context, i suspect you would find the sponsorship that you seek tout-de-suite!  ;-)

/walt

[Ste]

Dare I utter the word.. Twederation? 

https://github.com/inmysocks/TW5-TWederation

[C J]

@PMario,

Yes my boss, the owner of the company wants that so does his advisor. My manager also wants that but nobody want to spend much time. 
We use Jira for tasks management: creating, assigning and updating tasks from ''To Do" to "Done".
We use GitLab to manage the versions of our codes.
There is no CI/CD tool like Travis and Jenkins. I don't have experience with CI systems but I am ready to learn.

What I **really** want is a really private collaborative blog-like with tags and a clean interface.
I want to document :

• Projects goals
• Choices (why we did things the way we did) 
• APIs with the endpoints, what they return and the versions
• Tutorials: how to set up and start apps
• Use cases
• Related knowledge, for example I made a Kubernetes powerpoint based training last week for my team
• FAQ
• Updates

[Mark S.]

Note that out of the box TW doesn't do collaboration. AFAIK, the only multi-user tool is Bob. So you might investigate how that works on your company intranet.

[TW Tones]

Cedric,

My simple answer to " Do you think that it can be an suitable tool for me? " is yes, but it important to realise the following key points;

• TiddlyWiki is a platform on which a suitable tool can be built and evolved
• True collaboration is only possible on top of Bob which is a Node solution and thus may be a safe Intranet or LAN solution, but only an internet solution with a VPN by users into you LAN (my opinion)
• Jed is building more of the security and Internet facing features with Bob but he needs more funding support
• I have being working toward a simple serial editor method (Check in / Out) which would be another way to collaborate but I have not had much support and would need some funding as well, as I need to make a living.

Regards

Tones

[ludwa6]

@tones , can you explain: Why only in VPN-Intranet mode? Is it (a) To maintain integrity of InfoArchitecture (i.e. controlled vocabulary, taxonomy, naming conventions, etc.), or (b) Because of system security (i.e. risk of malicious hacking)... Or is it A+B both?

From my limited tech understanding, i would guess both, since "it's tiddlers all the way down"... But i think it's important to distinguish between these two forms of risk, because there could be different ways of handling each.

I've had a good browse around the Bob repo, b/t/w, but must say: i'm not really understanding what UseCase(s) it is designed to enable, and i've yet to find any working examples of it online.  Would be most interested to see, if anyone can point me to any... And if you have any demo of your solution-in-dev to show, Tones, that might also be instructive.

[Mark S.]

If you're making a collaborative wiki then one must assume that you are using some form node.js TiddlyWiki. You can't really do collaboration with single-file TW except via federation, which is more of a concept than an actual thing. With node.js you have multiple tiddler files. They can all be on a shared resource like dropbox. Each person then would have their own node.js instance running. Or in an office, there could be one server that everyone connects to. There are two problems.

1. Someone else can write over your tiddler while you're writing

2. You can't see someone else's changes without restarting the node server

You can solve problem #1 by having a gentlewomen's (gentlemen's) agreement for assigning tiddlers. Like "All my tiddlers will start with LUD" Bob solves problem #2 by automatically showing you changed tiddlers on the server.

Security on the net is hard. Companies get hacked every day. Putting a node.js instance directly on a public-facing internet server would probably be dangerous, even though node.js does have a facility for ssl certificates. VPN provides a more secure way for non-experts in security to share files over the net.

[Charlie Veniot]

I have no experience with multi-user TiddlyWiki, so please take with a huge heap of salt ...

Mark S. wrote: "You can solve problem #1 by having a gentlewomen's (gentlemen's) agreement for assigning tiddlers. Like "All my tiddlers will start with LUD" Bob solves problem #2 by automatically showing you changed tiddlers on the server."

I'm thinking that would be a good occasion to use tags (instead of adorned tiddler titles) for "tiddler ownership and tiddler assignment".  I.E. if you aren't the owner of the tiddler and aren't assigned the tiddler, then (as per gentlemen's agreement) do not be monkeying around with that tiddler.

So the advantage here of using tags instead of tiddler naming conventions:  the tags make it so easy to "query" (via filters) "your" tiddlers.

And then you can do some fancy aggregating of various tiddlers into some nice consolidated personal and team views.

For example:  When putting together an "aggregate notes tiddler" for some app, each teammate can create tiddler notes with "ownership tag" and "app name tag", and the related "app aggregate notes tiddler" can transclude all related notes via filtering of the relevant tags.

Just a thought.  Possibly over-caffeinated ...

[ludwa6]

@charlie : that's exactly what i thought, when i first read Mark's comment (GMTA :-)

@mark : thanks for explaining the two problem cases, and how Bob solves #2.  In this site i'm now playing with -not a Bob instance, but with tiddlers as separate .tid files- Github handles both 1 and 2 via Git's built-in version control affordances... But as i am editing this site via TiddlyDesktop (which is a node.js server, if i understand it correctly -yes?), i must take care to save the updated index.html file to my desktop when edit is finished, and then manage the Git workflow from my (Atom) text editor, such that i pull any updates from Github server before i push my update(s -any tiddlers edited, plus index.html) back thru Git.  Bit of a PITA for me, but worth doing, if i ever manage to engage any collaborators about this -at which time, we'll need to implement that "gentlemen's agreement" about some tagging convention TBD.

[Mark S.]

On Sunday, January 31, 2021 at 8:25:37 AM UTC-8 wrote:

I'm thinking that would be a good occasion to use tags (instead of adorned tiddler titles) for "tiddler ownership and tiddler assignment".  I.E. if you aren't the owner of the tiddler and aren't assigned the tiddler, then (as per gentlemen's agreement) do not be monkeying around with that tiddler.

That only works with existing tiddlers. You still have to have an agreement for new tiddlers, or you could be writing over someone elses work.  

[Charlie Veniot]

Aside lol:

Every time I see "gentlemen's agreement", I think:  https://twitter.com/brysonbort/status/941784237946089472

[C J]

Hi everybody, 
Sorry for the delay. Finally, I found someone in the room next to us who started a local Wikimedia project 3 years ago. I have decided to use this one.
Thank you for all your answers and messages. 
It was really great to have your support and see that some of you are thinking to solutions to problems like mine.

Best regards.

Cedric J.

[Charlie Veniot]

Good stuff, Cedric.

Regardless of wiki product and if you don't mind, let us know how you and your knowledge base project are doing.