TiddlyWiki as a target for generated help documentation

[Cade Roux]

I'm working on some data dictionary documentation and am trying to generate a basic prototype of an HTML-based help system.  At this point I haven't really chosen a platform or anything, but I'd like to just demo something simple as a possible starting point for the design discussion and I was wondering if I could use TiddlyWiki to give me a starting point instead of generating all the HTML framework around the pages completely from scratch.  What I'd like to do is generate a series of pages like this:

IndexPage:

• Index
• CategoryOne - link to page for everything in category one with a header about category one
• CategoryOne.ItemOne - link to page for just this data element
• CategoryOne.ItemTwo - link to page for just this data element
• CategoryTwo - link to page for everything in category two with a header about category two
• CategoryTwo.ItemOne - link to page for just this data element

CategoryOnePage:

Category One

Blah blah blah

• CategoryOne.ItemOne - link to page for just this data element
• CategoryOne.ItemTwo - link to page for just this data element

CategoryOne.ItemOnePage:

CategoryOne.Item One

Possible values are: etc - will generate a table here from my metadata

Source data is: etc

Update frequency is: etc

Narrative: An informatics person will have provided text and images to go here

So is there a way to generate a set of pages or the content for the pages and have them "loaded" into TiddlyWiki?

Then I could add a step to my build process to generate the TiddlyWiki content from my metadata and I could demo the generated wiki and then show how it evolves as the metadata gets updated/fixed corrected and the new TiddlyWiki is generated.

Again, it's just a simple prototype to see if this concept would fly before we figure out the whole scope of what we want to achieve.

Thanks in advance.

[Mat]

Hi Cade and welcome!

Reading your text I was thinking "OK, that is super simple" ...until you said

So is there a way to generate a set of pages or the content for the pages and have them "loaded" into TiddlyWiki?

Oh. That is a different matter. Someone just very recently posted something about this (within the last month) but the crucial thing is if you want your content to be actively integrated in TW or not. Now you state you have not quite defined what you want so may I suggest that you just do it all in TiddlyWiki? You can very easily export tiddlers as e.g ready made html pages or as e.g json files. Or just leave it in the TW because it is a single file which you can manage as a unit. 

Would that work?

I suggest you play around a bit with TW to see how it works so you can express your needs more in "TW terms".

<:-)

[Cade Roux]

Yeah, I have a large amount of metadata that is changing, and the source of that data is either going to be:

1. Originating in the metadata of the SQL tables (attached to the tables and columns) - kind of basic data dictionary things which will look like:

<DataElement><TableName /><ColumnName /><DataType /><Source /><ChangeEvents /><Discussion /></DataElement>

Where we would want to generate a page for every one of these automatically from the source code (mostly manually edited) during the build.  There might be also editable narratives to go with them.

2. It is going to be in rules that original in Excel (manually edited), go through XML and then become data in mapping tables.

These are kind of similar, but have much more data about the source data that matches the rule and the output data, plus the edited narratives are more likely to include screenshots and longer explanations.

<DataElement><TableName /><ColumnName /><DataType /><Ruleset /><Rule /><SourceCriteria /><Values /><Lookups /><Discussion /></DataElement>

3. Other things:  Perhaps pages of build results like any warnings, exceptions or errors in the rulesets in the current build process that we detected from #2.  Technically we already get these as logs or tables, but makes sense to include them in the set of pages if we have an HTML framework to put them in now.

It's unlikely I want to put TiddlyWiki on the front end of this process because I do need to check in structural changes like new tables, columns, views and procedures with their metadata all together.  Plus I don't think generating all my SQL from TiddlyWiki pages makes a lot of sense.  Plus, I would need to transition writing the rules from a spreadsheet to TiddlyWiki Tables - and we do occasionally use Excel macros to make these more functional for data input and validation.

There are two obvious approaches:  One is to generate the page framework from all the data we have and incorporate manually edited data somehow - like another manually edited source.  The other is to have manual set of pages which can embed automatically generated content as some kind of widgets or plugins of the form <Documenter.DataElement Category='CategoryName' DataElement='DataElementName' /> or whatever

There currently isn't any web-based application built that is hitting this data warehouse.  If I had that I could make some kind of service to serve up the metadata and plug it into manual pages as a widget or plugin.  I could also just build an app that lets you navigate the metadata and allows annotation and stores it somewhere and displays it all to the user.  But I didn't really want to build an app yet until we've explored the gaps in the data and the features people will need.

I could just going to generate a bunch of HTML pages with links.  But I would have to style them, have some framework, navigation, etc.  Again, not ready to build all that just yet - just looking to output something people can interact with and tell me what's missing so we can get it added somewhere in the process.

Basically, anything where I can load a big file like <pages><page name="Home">wiki markup here</page><page name="Category">wiki markup here</page><page name="Element">wiki markup here</page></pages> would be great.

In fact, that's basically what I am starting to generate for whatever presentation layer we end up using.

So I was looking to potentially push out a pre-built TiddlyWiki at the end of this process right now so people can browse it and see where the gaps are and what they would like to see.  I think ideally it would probably morph into something where they could edit any of the discussions or narratives and have that change recorded and save and potentially fed back through some change management process.  Who knows, maybe TiddlyWiki is the perfect platform for the whole thing with some kind of plugin.

Thanks,

Cade

[TonyM]

Cade,

Others have used tiddlywiki to consolidate documentation in the past. Using csv or JSON has the most tools and features available in 3rd party plugins. Import and export, so these may be good standards around to build data interchange.

I can't grasp the whole of your requirements but much of it touches on things I have done or researched. Do consider opening threads here in the forum with a specific or subset of things you are trying to do do so people do not need to understand your whole project to help.  It is easier for people to volunteer for issues rather than projects, although it is great you have outlined the bigger picture here.

How you are going to access and host your wiki can have an influence here. The node version also publishes every tiddler as a separate "static" html page, and you can export any tiddler as static html even from a single file wiki. Crafting of additional templates like those to export static html pages could be used to export html pages to build a standard html site, however as Mat suggested it would be in your interest to keep as much as practical in one tiddlywiki because of the control and global handling you can do.

Perhaps in the recent 5.1.20 release post you can see my comments on the Innerwiki Plugin, not that I am sure this will help with your project. With tiddlywiki the sky was the limit now I think it is the stars.

Regards

Tony

[Cade Roux]

I have started to look at the command-line available in node, and it seems like once I have all my pages in a single appropriate json file, then what I could do for my prototype is simply all a single line somewhere near the end of my build script:

tiddlywiki ./DataDictionary --init empty --import allmydata.json --rendertiddler $:/plugins/tiddlywiki/tiddlyweb/save/offline index.html text/plain

Then I have it all in a single file I can send someone to play with.  And that looks like a good start.

Thanks,

Cade