Proposal for improving TW Documentation - Structure (part 1)

[morosanuae]

Hello,

I want to propose a new structure for the TiddlyWiki documentation. In my opinion, improving the documentation in every aspect will make TW not only more useful but a lot more popular and attractive. The general idea is a more formal (standardized) and concise documentation structure. I don't mean to offend anyone but to share my experience and maybe to save other from the frustrations and obstacles I've ran into in the process of learning TW. Don't get me wrong, I'm not near an TW expert I just consider that the quality of the documentation can be raised a bit to make it look more professional.

Proposed improvements

• Less confusing and more concise chapter titles. - e.g. "Basic Usage" instead of "Learning"
• Higher level of abstraction and specialization – maybe more hierarchical levels.
• Chapters (and their contents) should have a more natural (logical) and progressive order.
• A clear distinction between different types of documentation (e.g. guides vs. references) - guides will be mostly used by beginners and references by advanced users.
• Chapters should be discrete areas of interests with a specialized role – not every user have time to read all the docs before creating the simplest thing - get things done now, read the concept behind them later (when there's time for this).
• The panel title should be "Docs" or "Help" not "Contents" (minor).

Demo link

Proposed structure -- see demo link above for a better version

GUIDES

• Welcome (a presentation similar to HelloThere)
• How to read the documentation
• Getting started
  • What is TiddlyWiki
  • Comparison with other wikis/knowledge management tools
  • Choosing an edition
  • ...
• Installation and basic configuration
  • Downloading and installing
  • Setting a backup routine
  • ...
• Basic usage
  • Site navigation
  • Create and edit tiddlers
  • Search tiddlers
  • ...
• Advanced usage
  • Creating and using macros
  • Using built-in widgets
  • ...
• Configuring and customize
  • Changing site title and subtitle
  • Setting a favicon
  • ...
• Administration and maintenance
  • Updating TiddlyWiki
  • ...
• Extending and developing
  • Creating and using plugins
  • Creating and modifying themes
  • Developing modules
  • ...
• Seeking for help
  • Known problems and limitations
  • Post a question on a TidldyWiki Forum
  • ...
• Helping the community
  • How to report a bug
  • How to contribute a fix/improvement
  • ...

REFERENCES

• Concepts
• Examples
• Dictionary
• TiddlyWiki Editions
• External resources
  • Forums
  • Community resources
    • Plugins
    • Sites
• About

Thanks!

[pmario]

hi, why did you close it?

[morosanuae]

Hello @pmario. It's simple: no one seems be interested in this right now. Maybe my proposal it's not that bad and I also know that things move at a slow pace around here, but I decided to make a demo first to show that is possible to implement it otherwise I don't think I will get much support. The group topic is still open though on TiddlyWikiDev (https://groups.google.com/forum/#!topic/tiddlywikidev/9hWr4q4Lryk) so you're welcome (and everybody else) to share your opinion about this.

[pmario]

ok ... There has been a relatively long thread in the group some time ago. ... The problem is, that the barrier contributing to the docs with github is way to high for most TW users and we don't have a better, manageable solution yet.

[tobibeer]

@morosanuae: There are some good points made. A demo would be great of this ...where you manage to also keep track how things were named beforehand, e.g. via some "previous_name" field or some such.

Perhaps a demo might seem futile and a lot of effort, but I imagine its much simpler to communicate actual aspects about it, rather than just imagine what it would be like.

[morosanuae]

Wow, I'm surprised that someone is interested in this closed issue. For me documentation problems are still the biggest problems with this app. I think it's the part that deserve the highest attention and priority and it's a mirror for the "professionalism" of the app. The documentation it's like comments in the code: when done right they are crucial for understanding the code.

Anyway I already have a demo (see below), but it's focused only on the structure of the documentation. It's not finished yet. I had planned to do the "dirty" job of mapping the old structure to the new one, but I guess this work entered in a "forever postponed" status.

@tobibeer please take a look at the demo and tell me your opinion. Only one tiddler is mapped, the "HelloThere" one, and already has a field name "source" that contains the old tiddler name. If you plan to participate in this discussion I can reopen this issue.

Demo link

[Jermolene]

Sorry I hadn't commented before. I'm very much in favour of refactoring the docs along the lines you propose. I've also thought for a while that it would be useful if the docs were properly published as a plugin (there is a plugin for the docs now, but it doesn't work well). So, one approach to let us make a fresh start might be to start a new reference documentation plugin from a blank slate. If you're interested in this approach perhaps we might start a new ticket.

[tobibeer]

I think one key point to approaching the docs differently is how to explore them. To me, while I appreciate the overall topic structure, the demo by @morosanuae clearly shows that the sidebar does not make for the best place, especially not with a lot of text.

So long as you know what to look for, search is fine. But what if you don't?

For all I can say / see, despite the perhaps better structure, I think those longer titles work even less in the sidebar. They would, however, work really well in a more "document" type table of contents. So, one thing possibly is that the docs clearly ask for their own starting page.

I find a comprehensive toc such as the one we currently have is entirely overloading the sidebar and asking too much of it.

On the other hand, I think working with documentation would be immensely improved if a search would reveal relevant toc entries and only those (and their parent entries, of course).

For me, one focus should clearly be on explorability which should come in the form of a dedicated docs search that shows results in a structured / perhaps tabbed manner... whereas the categories / groups used may well resemble @morosanuae's suggestion a lot more than our current sidebar.

[morosanuae]

@Jermolene I really want to get this going but let's make a little plan first on how to proceed. But, firstly, I think we should decide about the place in the UI where this new doc structure should go. I agree with @tobibeer that the sidebar may not be the best place for this type of content.

@tobibeer My proposal is referring, for now, only to the doc structure (types of panels and categories) not to the actual location in the UI. But if you ask me, I prefer a modal (popup) window with proposed structure and a dedicated search box, not interfering at all with standard content. And the doc page should be activated by a button in the sidebar or in some corner of the app. Anyway the location part is open for discussion.

[sukima]

Can I just propose a simple starter tiddler. A modal popup is an obtrusive UI. TiddlyWiki itself has already solved the problems in documentation by use of tiddlers. At any point one can click a link and have a tiddler open. A user already knows how to manage that and it doesn’t block the user from doing what he/she was doing. with a modal the user is forced to stop working just to read. lost focus on the subject the spawned the documentation.

I normal user experience would be to open TiddlyWiki.com in a new tab so the current tab can continue without interuption. Using a modal tells the user that your documentation is more important then their use of the wiki. Almost a “how dare you want to use the wiki you shiuld be treading the docs here I’ll force this on you.”

https://stackoverflow.com/a/361684 has more articulated rationals for why Modals are bad UI.

Disclaimer: Modal dialogs are a pet peve of mine

The simple and functional solution would be to have links to the documentation open a TOC / starter tiddler as part of the story river like any other tiddler and let the user navigate from there. This is the basis for TiddlyWiki and how it is explained in the getting started sections. It can be assumed users understand this UI.

[tobibeer]

have links to the documentation open a TOC / starter tiddler as part of the story river like any other tiddler and let the user navigate from there.

totally agree 👍

Another useful thing is something I once made for TWC called pagr. It's the thing at the bottom of each tiddler that allows you to paginate through the docs and I believe it will make people read more, compared to jumping back and forth between toc and content. In this case, the pagination navigation was automatically added to any tiddler in the toc and it would also have you move up and down chapters.

[morosanuae]

@sukima I think modals are obtrusive especially when they appear without your consent, but this is not the case. And yes, you should stop what you are doing just to read, it's a natural thing. We only have one set of eyes. And with a modal the actual working tiddler doesn't change it's location in the view. To be honest, to me, the story river is not the best navigation system anyway. Very often I get lost in it and I end up closing all the opened tiddlers and do a fresh start. In my personal wikis I use a plugin that shows tiddlers as tabs and only one is displayed in the story river all the time. Imagine what would be like if the browsers would not have tabs as navigation system. And I personally prefer that the doc pages not interfering with standard tiddlers.

What if not a modal but a special docked window with pin down capability? I agree that the users should not be distracted to much.

@tobibeer I believe the "pagr" thing it's a nice alternative but I think it has the same problem as other methods in distracting users from their work by stretching the original tiddler until the actual content is out of view. Can we make this "pagr" extend (display) to the side instead of bottom and automatically collapse the sidebar, at least for desktop screens?

[sukima]

You missed what I was saying about modals. Once the documentation is open you are forced to close the documentation in order to return to what you were doing. This means you can no longer reference the documentation at the same time as the focus of work. Even windows does not use a modal for help. They use a separate window. Chrome uses a tab, Vim uses an unobtrusive split. The only examples were a model is used is old 1980's DOS programs. And as I recall they were really annoying and obtrusive.

The Apple Human Interface Guidelines has this to say about it:

Minimize the use of modality. Generally, people prefer to interact with apps in nonlinear ways. Consider creating a modal context only when it’s critical to get someone’s attention, when a task must be completed or abandoned to continue using the app, or to save important data.

I don't envision documentation falling into one of those use cases. Also more specific to how documentation is handled:

Keep modal tasks simple, short, and narrowly focused. Don’t create an app within your app. If a modal task is too complex, people can lose sight of the task they suspended when they entered the modal context. Be especially wary of creating modal tasks that involve a hierarchy of views because users can get lost and forget how to retrace their steps. If a modal task must contain subviews, provide a single path through the hierarchy and a clear path to completion. Avoid using Done buttons for things other than completing the task.

[morosanuae]

@sukima Let's not talk only about disadvantages of a solution because it's not very constructive and I doubt a perfect solution exists. I understood already that you are totally against it. For me, the main advantages with the modal window is that a larger screen area can be used for showing content, that is independent from the crowded UI structure and is completely isolated from the personal content. It doesn't have to be complex also, just a few tabs. But this is just one proposal, it doesn't have to be perfect. I have also proposed a dockable and extensible side window with pin/unpin capabilities. This way the modal problem is gone and the doc window will always remain in sight. How about that?

Your proposal with a starter doc page would be indeed simpler but would have the same problem (maybe even bigger) as the modal window. A user should navigate back and forth from the content tiddler to the doc page.

I really wish that a reasonable solution will be found soon because I want to start working on this.

[gernert]

I have also proposed a dockable and extensible side window with pin/unpin capabilities.

Totally agree. We do have a 'Open in new window' button, so let's use it. I do use this in my plugins as well for Help panels.

[sukima]

I'll let this settle with one last observation. If the Story River is not ideal to display documentation then it is not ideal to display any information. If we need a completely different UI to show tabs and WikiText maybe it would be more useful as a community to address why the Story River is inappropriate for displaying content.

If the tools provided by the system are not sufficient we as a culture need to seriously debate why and how to fix it.

With that I will let others continue the discussion and consensus for next steps. I would not want my personal opinions to deter from developing next actions. This issue as a whole is a good idea and needs to move forward.

[morosanuae]

If the Story River is not ideal to display documentation then it is not ideal to display any information. If we need a completely different UI to show tabs and WikiText maybe it would be more useful as a community to address why the Story River is inappropriate for displaying content.

I need to emphasize that my opinions regarding the Story River are strictly my personal view, maybe others have a completely different opinion. And I don't dismiss your proposal also. But in the end, whatever the chosen path, we need better documentation organization and content (capabilities). My hope is that if we'll have a well structured doc system maybe more people will be willing/attracted to contribute to it. I have also the desire to contribute to the docs, though it will be a little difficult because I'm not a native english speaker.

[Jermolene]

Something that I should have mentioned before is to congratulate @morosanuae on a beautifully clear ticket, and the accompanying demo. There's no question that it's much more rewarding to discuss ideas when there is a concrete proposal.

One little thought on the demo: I'm not a fan of clicking on a folder icon to open a topic in the TOC. At the moment there's no visual feedback that the folder is open. That can be fixed, but I'm also not convinced that the icons work in another sense: they suggest a false distinction between tiddlers that are headings in the TOC and those that are leaf nodes. Furthermore, the folder icon suggests a classical hierarchical containment arrangement, which isn't quite what we've got here. I still believe that the disclosure triangles are more idiomatic for a web application; files and folders are the stuff of the desktop

It seems that we are now discussing quite a few different and interesting topics here:

• The original topic of how to structure the docs
• How the docs are presented, with reference to the use of the sidebar in the demo
• How the docs are distributed (the point that I raised about making it easier to reuse the documentation as a plugin)

I'd be quite keen to try to keep this thread to the core topic of evolving the hierarchical structure of the docs, and discuss the other issues elsewhere. The current TOC is pretty poor, and so I think there's "low hanging fruit" in just fixing the structure, independently of the other possible improvements.

[morosanuae]

@Jermolene Thanks, I really appreciate it. I try to do my best every time.

Regarding the folder icons I've used, I think this is secondary importance for me at least. Initially I wanted to use books (more realistic) instead of folders but I abandoned the idea because of laziness. I don't know if you have noticed it but I didn't use heading tiddlers. The folders are just containers and nothing more (like chapters in a real book). In the original TiddlyWiki chapters are also content tiddlers. To me this was just confusing so I didn't use them. Anyway I think I don't really care what type of icons will be used in the end.

I'd be quite keen to try to keep this thread to the core topic of evolving the hierarchical structure of the docs, and discuss the other issues elsewhere. The current TOC is pretty poor, and so I think there's "low hanging fruit" in just fixing the structure, independently of the other possible improvements.

I agree. So what's next? Now that I have your (and others) support can I try to remap the old doc to the new structure? I'll start with only 2 sections: "GUIDES" and "REFERENCES". Is this ok? I'm waiting for your answer.

And for the rest of the topics I will create separate issues.

[Jermolene]

Hi @morosanuae

So what's next?

I think the way to get this done is to cut the task up into smaller chunks. In particular, I think we need to avoid trying to do the update as one big bang. Apart from anything else, in the time it would take to finalise the PR there would likely be a lot of changes to the documentation, leading to rebasing hassles.

So, can you see a logical way to break things up into (say) half a dozen smallish PRs?

[morosanuae]

Hi @Jermolene I don't really have a strategy for breaking things up right now, but I think it's to early to think about making PRs anyway. It's a big change and I don't want to screw it up. So, I want to be sure first that I can remap the old documentation to the new structure without major problems in my demo site. And if successful I will think about a strategy for commiting the changes in small chunks. I will come back here as soon as I finish .

[morosanuae]

@Jermolene, @tobibeer, @sukima, @pmario, @gernert and others: Hello everyone again,

I have returned, as promised, after a lot of work in a relatively short time, and I invite you all to take a look and share your opinions. I've created a dedicated wiki just for this project: http://new-docs.tiddlyspot.com Please, check the "Guides" and "References" sections (the ones with blue and bold title) in the "Help" tab in sidebar for the new structure. You can also reference and compare the new structure to the old one : "Contents old" (in red and bold title). The work is, let's say in BETA status, so it's not completed yet but I thinks it renders my proposal well enough. There are many things left to do until the new structure will be completely functional: renaming tiddlers, manipulate the content of some tiddlers (aggregate or split) etc., and I think from now on this project will need some community support.

Thanks.

[Jermolene]

Hi @morosanuae thanks, that looks like a great start.

I'm worried that in both cases there is still too much overlap between the top level categories. For example, the difference between "Configuration and customization", "Administration and maintenance" and "Extending and developing" isn't clear at a glance. There's also something a bit arbitrary about the split between "Basic usage" and "Advanced usage".

As well as the documentation itself, it would be good to see updates to the "meta-documentation", the documentation about the documentation. If this is going to go ahead, it's important that people coming along in the future should be able to understand the decisions taken so that they can make their additions or corrections harmoniously. So, for example, we should document the criteria for inclusion under each of the major headings.

[tobibeer]

As suggested in the groups, I am very much for splitting up TiddlyWiki.com into well, subdomains / -folders / -wikis, as suggested here:

https://groups.google.com/d/msg/tiddlywikidev/W53j-dHN1wE/9oQNP6_4BwAJ

That way, we don't end up overloading the sidebar too much. Plus, we separate concerns not just in terms of manageability of repos but also in terms of representation. For example, I think we should have all of the suggested tw-editions represented by both, a unique color and icon, then used by links to contents of those editions.

That way, we can have a "references" wiki with it's TOC, a "Learn" wiki with another TOC, a "Tips" wiki with yet another TOC or even no toc, but a different way to explor tips, rather than overloading one sidebar to cover it all.

[morosanuae]

@Jermolene I personally don't think we can solve all the problems or make a perfect system. I'm just trying to make things a little better, for me and others. Even with the shortcomings you have mentioned I still think that the new structure it' s more clearer and meaningful that the current one. Why? Mainly, because it is more formal (used by many other applications/systems) and that means that a lot of people should recognize it and accommodate with it much easier. And for users that are not used to this type of structure, we can guide them, just like you said. After all, this is the purpose of the "Guides" section, to guide the users to not only use the app but to think about the app, to construct a well structured mental model. I believe that in this way they will become advanced users much easier. I thought that the advantages of the new proposed structure will be obvious, but I was wrong. So I will try again to explain my point of view.

The proposed chapters are trying to group documentation based on type of tasks a user can perform in relation to the app. I think that the overlap is impossible to be eliminated completely, but in the end I personally prefer overlapping instead of not knowing how and where to find a specific documentation resource.

Advantages:

• More formal/standard structure --> maybe more popular to the majority of users.
• Self-explanatory chapters names
• Chapters group specific types of tasks in relation to the usage of the app.
• Clear distinction between different types of documentation resources: "Guides" and "References"
• Chapters are designed to be parsed in a more natural and progressive order.

Chapters meaning

• Getting started = introductory material
• Basic usage = intuitive and simple tasks that an average (non-technical) user can complete. Maybe some users will not be interested in macros or widgets, only creating tiddlers to store some basic information.This is a foundation for the next chapter (Advanced usage).
• Advanced usage = more technical pages that require more experience and knowledge (a lot more dependencies). This is the main foundation for the developing chapter.
• Configuration and customization = knowledge that help the users to customize the app based on their specific needs.
• Administration and maintenance = knowledge to that help the users to keep the system manageable and working smooth (ex. making backups, eliminate redundant tiddlers, finding dead links etc.)
• Extending and developing = I'm sure this is pretty obvious: using plugins and create what a developer usually creates
• Seeking for help & Helping the community = I think they speak for themselves.

In conclusion, please let me know if you really want to support this initiative because otherwise I will have to abandon it. It's a lot of work and I don't want to be in vain.

@tobibeer I understand your point of view, but let's focus on the doc structure for now. We will open a separate issue with how the help system should look like and how it will be accessed in the UI.

[Jermolene]

Hi @morosanuae

Part of the background here is that we have had many attempts to improve the documentation in the past, and they have usually floundered. A big part of that is the scale of the problem: there's an awful lot of existing documentation, and so any significant improvements need to be applied to all the existing material, and any new material that is subsequently added.

The scale of the problem means that this is not a job for a single person; we need all the available help we can get. The implications of that are quite significant: the big task is to design the rules for making the documentation, and then there can be lots of little tasks to apply those rules to specific parts of the task.

Hence my feedback: for a prototype it's fine just to see the documentation, but if we're going to implement these changes then we need to document those rules so that other people can participate in the task.

In conclusion, please let me know if you really want to support this initiative because otherwise I will have to abandon it. It's a lot of work and I don't want to be in vain.

You have my support, and I'll help you where I can.

[morosanuae]

Hi @Jermolene and thanks for your support.

The scale of the problem means that this is not a job for a single person; we need all the available help we can get.

My personal opinion is that this is applicable more to the content creation part and less to the structuring part. I already made an almost functional structure by simply reclassifying the old doc pages in just a few days. My work is far from over but I think that I've managed to demonstrate that it is a feasible project.

The implications of that are quite significant: the big task is to design the rules for making the documentation, and then there can be lots of little tasks to apply those rules to specific parts of the task.

I think you should be more specific about that. If you have something concrete in mind please make a list of tasks/features we need, and I will try to do what I can or at least share my opinion.

Hence my feedback: for a prototype it's fine just to see the documentation, but if we're going to implement these changes then we need to document those rules so that other people can participate in the task.

No problem. I will do that soon. This will have its place n the "Helping the community > Improving the documentation" section. I've already explained what's the purpose of each chapter. In the end we will have a formal meta-documentation also.

IMPORTANT My question is, if this is such a big scale and complex project, would it be better if we create a TiddlyWiki branch just for this? This way it could be modified and tested without worry until it's ready to be integrated into the "master" branch.

Thanks.

[sukima]

would it be better if we create a TiddlyWiki branch just for this? This way it could be modified and tested without worry until it's ready to be integrated into the "master" branch.

Isn't that what your personal fork is all about? We can simply point contributors to your fork where you can manage and merge pull requests. Then when ready to merge into here create a PR with all the fixings completed.

Or do you feel a branch in TiddlyWiki is more functional then a branch on your repo?

[Jermolene]

My question is, if this is such a big scale and complex project, would it be better if we create a TiddlyWiki branch just for this? This way it could be modified and tested without worry until it's ready to be integrated into the "master" branch.

No; as I mentioned above, I think we need to structure the effort as lots of small PRs that can be merged quickly. One big branch that takes months to merge will just make it hard to manage the maintenance of the documentation in the meantime.

I already made an almost functional structure by simply reclassifying the old doc pages in just a few days. My work is far from over but I think that I've managed to demonstrate that it is a feasible project.

The reason you've been able to do it in a few days is, with respect, because it's the easy part of the job. In your prototype there are many stubs for new tiddlers that need writing. Are you intending to write them all yourself?

[tobibeer]

@morosanuae,

My personal opinion is that this is applicable more to the content creation part and less to the structuring part

Taking tiddlywiki.com out of the core repo makes all the sense in the world.

However, if we also move the docs out ot the main / landing page, restructuring goes hand in hand with, say "content revision" (owed to otherwise broken links, unless we invented some awareness as to what tiddler is in which subwiki).

I think your changes also pretty much require we do not just one such "repo extraction", but practically a few, incl. dev... and other "editions" that should actually be repos AND separate wikis.

Once we've defined and set up the repo strucure, we should freeze all tw.com site contents for now, start moving stuff to the respective repos, keep track of what's moved where (so as to not forget a single tiddler) and then release the new overall site structure.

The repos we need to do that can be created even half a year in advance. I have absolutely no problem at all to polish the new structure and contents even for a few months before we make the move from tiddlywiki.com to tiddlywiki.com/docs, tiddlywiki.com/dev, tiddlywiki.com/plugins, tiddlywiki.com/languages, tiddlywiki.com/node, tiddlywiki.com/tips etc...

But, if we make a big undertaking such as yours, we should make it one big move, not two big moves. Because, if we were to only try to figure out how to take the docs out of the core repo but overload the docs with all your new structure and content changes we will very likely not find the energy to reconsider the overally structure of the site. And that, to me, is a lost opportunity, a big one... which will involve spending significant effort in squeezing your changes on top of what's there.

To not have this sound as "theoretical" as it seems right now, I'll be uploading a demo shortly to give you a hint of what I mean and where I think we should be headed... and that well includes decisions about where your well thought out content changes find their eventual place.

By no means I am discouraging your effort or imply they're in vain. They just should not at all come in the form of a standalone change, imho, esp. not if they come with the respective guidelines @Jermolene wants to see regarding how to manage the new structure.

[morosanuae]

Or do you feel a branch in TiddlyWiki is more functional then a branch on your repo?

@sukima I don't really know, sorry. I just assumed this is the correct way of doing things, that an official branch will attract more attention than an obscure one.

No; as I mentioned above, I think we need to structure the effort as lots of small PRs that can be merged quickly. One big branch that takes months to merge will just make it hard to manage the maintenance of the documentation in the meantime.

@Jermolene Ok. You're the expert here, but please let me understand clearly what you mean. Do you want to merge those small PRs directly into the "master" branch? Doesn't mean that we will integrate incomplete work in it, even if a plugin? Should we create a separate plugin?

The reason you've been able to do it in a few days is, with respect, because it's the easy part of the job.

I guess this is the "low hanging fruit" you've mentioned before ;) Even if so why didn't anyone else bothered with it? Isn't the documentation a very important aspect of the app? I think this is one of the first points of contact between new users and the app. It has much value already but some things are quite difficult to find and to be putted together to form a clear image of a particular subject.

In your prototype there are many stubs for new tiddlers that need writing. Are you intending to write them all yourself?

I would lie if I say no. It really did cross my mind. I can create the content in time, but I will definitely need some help because I'm not a native English speaker. Anyway I don't think that are too many stubs and also it's not the type of work that can be done overnight. It would take some time.

[Jermolene]

@tobibeer I'm afraid that I am not in favour of splitting the TW5 project into separate repos. This article will give you some of the background: https://danluu.com/monorepo/

@morosanuae nobody is saying that the documentation isn't important; just that improving it is much harder than it appears.

[tobibeer]

Ok. You're the expert here, but please let me understand clearly what you mean. Do you want to merge those small PRs directly into the "master" branch? Doesn't mean that we will integrate incomplete work in it, even if a plugin? Should we create a separate plugin?

Plugins are never merged into the docs unless they are needed to facilitate working with the docs.

The overall plan is to have the core (TiddlyWiki itself) and the docs / site (tiddlywiki.com) be two separate repos, so they can be managed separately. However, seeing as how I was asked to be one of the maintainers / admins of that tiddlywiki.com repo, I would very much be in favor of splitting things up considerably more... make it modular, and easy to maintain... all while separating concerns, where concerns need separating.

I want us not just to ask:

• What is a core feature?
• What is documentation?

I want us to distinguis concerns a whole lot more:

• What is a core feature?
• What is documentation?
• How to learn? (that is not at all the same as the concise docs!)
• What are tips? (e.g. how to achieve XYZ, not how to use feature ABC!)
• What is plugin related info?
• What are community references?
• What is node?
• What does a dev do?
• etc...

...and I think these things should not be intermingled in one big master "documentation" wiki.

[tobibeer]

@Jermolene: I don't mind if we keep one repo. However, the job for you maintaining it stays the same, unless you invite others to share the responsibility by defining clear rules as to who gets to approve AND merge what type of PRs.

However, even if we keep the "one repo approach", and I immediately understand the charme of it without even reading the article, two things should happen nevertheless:

1. we should have separate wikis for the separate concerns mentioned above
2. you should (be able to) allow others to decide on merginging updates precisely to those domains, with your veto of course => since we're still operating on the same mono-repo 👍

[Jermolene]

However, the job for you maintaining it stays the same, unless you invite others to share the responsibility by defining clear rules as to who gets to approve AND merge what type of PRs.

I do plan to move the TiddlyWiki5 repo to the TiddlyWiki organisation so that I can authorise others to handle issues and PRs.

we should have separate wikis for the separate concerns mentioned above

I take this discussion to be about the guide/reference docs in the "tw5.com" edition, not about the broader docs available at tiddlywiki.com. As we've discussed elsewhere, I'd be very keen to have a tips.tiddlywiki.com (or similar) that has a much lower bar to contribution than the core docs.

[tobibeer]

I take this discussion to be about the guide/reference docs in the "tw5.com" edition, not about the broader docs available at tiddlywiki.com

Well, not really, because @morosanuae thoughtfully tried to translate the existing docs to some new place/structture ...which should possibly be new placeS instead. It makes a difference (to me), if we rearrange contents into documentation, tips or tutor/learning stuff. Those are (at least) three places to me. However, at this point with @morosanuae suggestion we are talking about rearranging some monolithic documentation. And I do not think that the contents on tiddlywiki.com are that, actually. Some of those contents should end up be moved, to say "tips". Other contents should be moved to, say "learning"/"tutor".

[morosanuae]

I see that the discussion is drifting away from my actual proposal (and the practical implementation) and is beginning to grow in complexity, becoming a little hard to understand also. I really wanted to keep things much simpler. Now I don't really know what to do next. I consider I have done my part for the moment and I will wait to see if a solution that will make everyone happy will emerge from this. I'm afraid that this is also predestined to die eventually. Who knows?

[tobibeer]

I'm afraid that this is also predestined to die eventually.

Don't think so at all. It's really more this:

I consider I have done my part for the moment and I will wait to see if a solution that will make everyone happy will emerge from this.

[pmario]

@morosanuae

.... Even if so why didn't anyone else bothered with it?

You are one of the view, who was OK with the existing structure, to contribute to the github repo. ... As I wrote in my second response. For many users github is a barrier. ... So some other users presented ideas to improve the docs, but someone else should do it. ...

Isn't the documentation a very important aspect of the app?

... It is!

I think this is one of the first points of contact between new users and the app. It has much value already but some things are quite difficult to find and to be putted together to form a clear image of a particular subject.

There has been an overall structure change some years ago. ... Which imo improved the usability a lot. ...

But improving documentation is an ongoing process. ... And it has to be done by people, who actually love to do documentation. ...

If Jeremy would open up the repo for several contributors with merge access, this wold take away a lot of work for him. ...

We just would need to write down some rules, how the workflow needs to look like

[pmario]

@tobibeer I'm afraid that I am not in favour of splitting the TW5 project into separate repos. This article will give you some of the background: https://danluu.com/monorepo/

... I did have a similar discussion with Jeremy, several times already :) ... For me "A single repo .. it is"

I do know several ways to create an automatic CI/CD workflow with Jenkins. ... I use one for my file-backup addOn, automagic signing process.

So we can have the following workflow if we want:

• A user wants to improve documentation
• The user forks the TW repo
• user makes changes and creates a pull request
• If the PR is mergable
• Jenkins creates a public draft edition with the PR applied
• Everyone can have a look at it and can comment at the PR here at github.
• Everytime a new commit to the PR is made, Jenkins builds a new draft edition
• If there are eg: 2 LGTM from authorized contributors, ..
• The PR will be merged.
• Jenkins publishes the new version to tiddlywiki.com
• It would be possible to add a gitter-chat to the whole equation, if we want a live chat feature too.

[tobibeer]

Here's a very, I really mean very tentative demo of what I'm shooting at, structurally speaking:

http://tobibeer.github.io/TiddlyWiki5

And, it does have implications, content-wise ...that I will leave you pondering for now.

[morosanuae]

@tobibeer I really like your demo (and idea) but I don't know all the implications of this. It looks like there are separate wikis for each major section, like you said, am I right? Is this going to improve the overall performance of the app?

But in the end, I think I'm used to a more classical approach though, like the one in the desktop apps, where the docs are not really a part of the app. And I don't know if the upper toolbar is the right place for a doc menu. I personally prefer putting shortcuts to the most used tools in there.

[pmario]

And, it does have implications, content-wise ...that I will leave you pondering for now.

I do like the general idea. ...

What I don't like:

• is the time needed to switch between the different TWs.
• search is not possible anymore. ...

So if we would go this path, we would need to implement a complete index in every TW, that links to every other TW. ...

So in the end 1 file is preferable for me.

[tobibeer]

Hi @morosanuae, to stop overloading your issue, I created a new one. ;-)

Let's discuss the pros and cons of one big wiki vs. multiple ones there. After a "poor nights sleep" ;-) ...I am now quite agnostic to whether we make it monolithic or use separate wikis. However, we definitely should decide.... for the long run, as this will have implications as to how to eventually make your suggestions "explorable" on TiddlyWiki.com

[pmario]

I am now quite agnostic to whether we make it monolithic or use separate wikis.

I think, we can have both. ... IMO it's just different "build" parameters. So we can automatically create, whatever we want.

[morosanuae]

Hello everyone,

I see that this is getting nowhere fast, as I have predicted. There's too much talking for me and few concrete actions. Maybe this is one of the reasons we still have so many opened issues. I have proposed a simpler and feasible solution but this has transformed into a "monster" that is too big and too "dangerous" to be handled. So before I close this issue I let you vote if you prefer this variant over the others. Even if rejected I will keep this proposal in my sites for others to use it.

[Jermolene]

Hi @morosanuae I had some comments about the general difficulties with contributing over in #2997.

The work you've done here is promising, but looking back in the thread I don't think you've taken on board my comments about how to actually execute the changes. These comments are based on my experience of both failed and successful earlier documentation improvement efforts.

I see that this is getting nowhere fast, as I have predicted. There's too much talking for me and few concrete actions

There's no actionable PR at the moment so it is inevitable that we are at the "talking" stage. What concrete actions would you like to see at this point?

[morosanuae]

Hi @Jermolene and thanks for caring. It means a lot to me.

I don't think the problem here is that I don't follow your recommendations because I really do need your experience and advice and I really do want to follow your recommendations. The main problem for me is that the are so many different opinions that eventually lead to a dead end, and that is really frustrating. It would be much easier if the people would just say yes or no, or vote. Because I currently don't know if others like/support my proposals or not. After all the discussing it's not clear for me yet if I should continue with this or not. There are too many unanswered questions, and this is also very frustrating.

So, to answer your question I need some answers to my questions first:

1. Are we going to follow this route or not? And I'm not talking about UI here, just the content. It can be as simple as a 2 tabs tiddler (Guides | References) for a start.
2. Can we make an official "Alternative documentation" plugin? This way maybe others will help.

[Jermolene]

Are we going to follow this route or not? And I'm not talking about UI here, just the content. It can be as simple as a 2 tabs tiddler (Guides | References) for a start.

In all honesty, It's too early to say. As I've said, what you've got so far is promising, but I think more needs to be done before we can make any further decisions. But right now there's a lot going on in your demo and it's not easy for me to understand precisely what you mean by "this route".

The only decision that matters in an open source project is the decision to commit a PR. We can only make that decision when we have the actual PR to consider. It sounds like you want a decision on the adoption of your approach, but right now that's not possible: all we see are some example headings (and I've critiqued them above).

Can we make an official "Alternative documentation" plugin? This way maybe others will help.

Are you referring to my proposal to refactor the docs as a plugin? It wouldn't be an alternative; it would be a migration.

[morosanuae]

@Jermolene

By "this route" I meant the structure that I've proposed. @tobibeer has proposed a completely different approach.

As I've said, what you've got so far is promising, but I think more needs to be done before we can make any further decisions.

From this I understand that you need a complete working system before taking into consideration. But that's a big obstacle for me because I don't think a I want to invest time and effort in something that it will never be accepted. It's too risky. That was the purpose of the demo in the first place, to attract attention/support from others.

The only decision that matters in an open source project is the decision to commit a PR. We can only make that decision when we have the actual PR to consider.

Can I make a PR with only a fraction of the work, let's say the "Getting started" section? Wouldn't that be useless?

Are you referring to my proposal to refactor the docs as a plugin? It wouldn't be an alternative; it would be a migration.

Not really. I know that a doc plugin already exists because I'm using it, even if it has some problems. I was referring to the creation of a separate doc plugin that will eventually replace the old one.

In conclusion, I think I will develop my own plugins from now on. What you said in #2997 about innovating via plugins is not really a solution for this because there are so many useful plugins out there but few knows them because there isn't a true centralizing/rating platform.

[Jermolene]

From this I understand that you need a complete working system before taking into consideration. But that's a big obstacle for me because I don't think a I want to invest time and effort in something that it will never be accepted. It's too risky. That was the purpose of the demo in the first place, to attract attention/support from others.

No, rather the opposite: I'm advocating splitting the work into small PRs that can be easily merged. My comment here was just that we don't currently have an actionable PR, and therefore there is not yet any decision to be made.

Not really. I know that a doc plugin already exists because I'm using it, even if it has some problems. I was referring to the creation of a separate doc plugin that will eventually replace the old one.

The current doc plugin doesn't work well because too many of the tiddlers expect the content not to be in shadow tiddlers. My proposal above was to fix those issues and refactor things so that the documentation only exists as a plugin.

What you said in #2997 about innovating via plugins is not really a solution for this because there are so many useful plugins out there but few knows them because there isn't a true centralizing/rating platform.

Isn't that a separate problem? We can't use the lack of a plugin library to justify putting things in the core.