Improving Developer Documentation

[ldorigo]

Hey there!

As I mentioned in the chat and probably somewhere else on GitHub, I am planning to dedicate some time this summer to get a good understanding of TW's code, and improve existing documentation along the way.

I'm thinking to keep pushing files to this pull request, so that experienced developers can give their opinions, answer eventual questions and review my changes.

I would encourage anyone familiar enough with the codebase to follow this pull request and comment along the way.

Let's build a better documentation for TiddlyWiki 👍

Here is a proposal for a hierarchical structure for the documentation:

• Introduction: Contains a broad description of TW's architecture, defines basic concepts. Will contain a reworked version of current intro's.
• High-Level overview: Contains detailed but high level descriptions of the different components of the app
  • Microkernel: Description of the boot mechanisms and kernel
  • Core Plugin
  • User Interface: Description of the rendering process, both for tiddlers and for the general UI of the app
  • Data Persistence: Description of the various mechanisms for saving data
  • Modules: Description of the various modules. Should this be in the "core Plugin" section?
  • Hooks
• Detailed Documentation: Will contain a code-level description/explanation of the various parts of the app. I was thinking to have a 1:1 mapping between code files and tiddlers in this section. This would allow programmers to quickly jump to the documentation while coding. It could actually even be auto-generated via JSDoc-style comments... It would clutter files more, but it would also mean that the code can be understood without needing to refer to external documentation. Ideas?
• Contributing: Will contain all the information relevant to people who want to contribute to TW, including:
  • Setting up the development environment
  • Style guides
  • Documentation style guides
  • Tests
  • ...
• Various How-To's: General tutorials that don't fit elsewhere in the documentation.

[Jermolene]

Hi @ldorigo thanks for picking this up, improvements here are sorely needed and will be much appreciated. I'll review the changes you've proposed and leave any relevant comments.

[Jermolene]

Hi @ldorigo I've briefly reviewed the changes and very much like the direction you're taking of pruning and rearranging what we've got before adding to it.

One thing I'd like to see is to document the documentation style guide, just as we do for the main wiki under "Documentation Style Guide". A big part of what you're doing will end up being to evolve the rules and standards for how to make the docs, and making that explicit makes it easier for other people to join in.

[Jermolene]

It looks like maybe this is part of a scheme for dynamically generating sequences of documentation. If it's not used then I agree it can go.

[Jermolene]

This tiddler is transcluded by the tiddler TiddlyWiki on NW.js

[ldorigo]

Good idea with the documentation guidelines. I'll write a draft as soon as I have a basic structure for the already present files.

[ldorigo]

Hey there, just a quick message to let you know that I'm on vacation for the next two weeks, so I won't be committing anything for that time. I have all intentions of finishing it once I am back!

Btw: Git is showing a huge amount of changes, so it may be hard to review everything - but I usually mark with TODO the parts I'm uncertain about. The rest is mainly reorganizing, fixing typos, correcting the English a bit (you can almost hear the German accent in Heigele/Jurke's documentation :-) ) and deleting duplicate information, so there's not too much risk of doing things wrong.

[PaulReiber]

It's awesome to see tw5 getting better documentation - thank you!

[Jermolene]

Hi @ldorigo how are you getting on with this? Is there a build that people can look at?

[ldorigo]

Hi @Jermolene and anyone else following, apologies for a long time without news. Life caught up and I had to spend most of august away from a computer!

I'm now back to university and planning to wrap up the "high level" part of the documentation - 98% is done, I just want to finish proofreading what I have before officially asking for reviews :-) You can already give it a look, just checkout my branch and do

node tiddlywiki.js editions/dev --server <port>

[Jermolene]

Hi @ldorigo apologies for the slow response on my part. Would you be able to resolve the merge conflicts and post a build somewhere? More people would be able to look at it and help if it were available on TiddlySpot or a GitHub Pages account. Many thanks!

[ldorigo]

Hi Jeremy, no worries, it's really my fault for letting this hang so long.

I solved the merge conflicts (the remaining one can be safely ignored).
Just gave a look at where I was and I think it's fine to put it up for reviews, I'm currently trying to figure out how to make a tiddlyspot page ;-)

[ldorigo]

It seems that making a github page is much faster, so here goes:

http://ldorigo.github.io/

I was wondering, is it necessary to have both the application and the normal/developer documentation in a single repository? (I am sure I read something about you wanting to keep it all together somewhere, but don't remember where/when).

It seems like it would be much easier to manage if they were into separate repos. I know you are planning to migrate to an organization repository, maybe it's something to do when you do the switch?
At the moment the issues and PR's of the main repo are cluttered with all sorts of documentation improvements, it would make sense to have a separate github for documentation (that would have a much higher "throughput" as PR's are mostly small and shouldn't always require your personal approval).

[Jermolene]

Hi @ldorigo

I was wondering, is it necessary to have both the application and the normal/developer documentation in a single repository? (I am sure I read something about you wanting to keep it all together somewhere, but don't remember where/when).

I do think that TiddlyWiki5 is much easier for users to work with if the main repo is self contained, and so I am not in favour of splitting out translations or documentation into a separate repo. There's nothing to stop people working on a separate fork, though.

At the moment the issues and PR's of the main repo are cluttered with all sorts of documentation improvements, it would make sense to have a separate github for documentation (that would have a much higher "throughput" as PR's are mostly small and shouldn't always require your personal approval).

I've learned the hard way that everything requires at least the level of review that I would give it myself. Even trivial seeming documentation updates can break established documentation conventions.

[ldorigo]

Of course I wasn't suggesting that the documentation PR's shouldn't be reviewed - it was more about not having to do all the reviews yourself (as it takes time from developing/reviewing code). But of course I understand that you would rather keep it centralized and under control as it is easier for you to manage.

Regarding the developer documentation, could you let me know if there are particular points that need to be reworked before merging ? Of course there is still much work to be done, but what there is now can be a good starting point for further improvements. I deleted most duplicate information and adopted a more coherent style overall.

[ldorigo]

I now actually fixed the merge conflicts (my git-fu was a bit dormant), and included the changes you made regarding continuous integration.

[ldorigo]

I tried to change the PR's base to the right branch (for the new CI) but messed up, working on it now.

[ldorigo]

Ok, the git part should be fine now. Let me know how to proceed from here :-)

[pmario]

Overall I do like the reading experience and the new toc-like structure.

Some of your tiddlers have 2020 dates. ;)

[pmario]

What is this field for? ... Tags have a list field, that can be used to sort the TOC if needed.

[pmario]

I did create a video playlist: see: https://www.youtube.com/watch?v=3h1nemtQLRI&list=PLuiC_HFhI4OxtThoQf92ws875R9zgNGSd

It may be linked somewhere?!

[ldorigo]

Oh, great. I need to watch that. I'll add the link, too.

[pmario]

To me it looks like this field will create a lot of maintenance (pain) in the future. It should be removed. We need to use the built in mechanism!

[pmario]

TODO: It would be nice, if the hooks could link to "real world" examples, if we can find some ;)

[ldorigo]

Yes, very much so. I only aggregated/cleaned existing documentation so far, there is still a huge amount of work to be done to actually make it complete.

[pmario]

We should set: http://ldorigo.github.io/#%24%3A%2Fconfig%2FNavigation%2FopenLinkFromInsideRiver to bottom ... So it will be possible to CTRL-clck links and get the story river in the right order.

The default setting create a "reverted" river, which imo isn't the best reading experience.

[ldorigo]

Uhm, yeah. That's what I get for putting in timestamps by hand. I'll look at a way to unify the dates.

Tags have a list field, that can be used to sort the TOC if needed

What do you mean exactly? How can we accomplish what I am doing with the toc-order field? I put it there so that the table of contents can be ordered (you would expect introduction to come before the rest, for example). If you give me an example I'm happy to modify that.

[pmario]

see: https://tiddlywiki.com/#list-tagged-draggable%20Macro:%5B%5Blist-tagged-draggable%20Macro%5D%5D%20ListField

TW uses a list field, that is automatically used by <$list> widgets. It's used for sorting. ... You could make 1 dev-tiddler, that contains some drag&drop lists. So it's easy to mess with the order.

The end-users should have "default" TOCs.

[pmario]

also see: https://tiddlywiki.com/#Order%20of%20Tagged%20Tiddlers

[ldorigo]

Oh, ok. So I've basically been using toc-order as my own list field, it should indeed be replaced by the official way to do it. Will do that now.

[ldorigo]

No, apparently I misunderstood how it works: I thought each "child" tiddler should have a list: field specifying its order. But it's the other way around, right? ie. each parent needs to have a list: of all its children.

I'm modifying it now.

[pmario]

The <<list-tagged-deaggable>> macros make sorting easy and they automatically update the list field

[ldorigo]

The <> macros make sorting easy and they automatically update the list field

Ah, nice, sounds like the easiest way. Before I can do that though, could you maybe help me fixing a problem with the developer documentation edition in the sources: it seems like there is no saver configured (so at the moment it's not possible to work on the documentation wiki and save it). So far I have been making all the changes in a text editor.

I don't know enough to make it work in a sensible way, maybe you could give a look at it? Then we can use the <<list-tagged-deaggable>> to order the sections (which is indeed easier than typing all the list: fields by hand).