Thanks for the Effort, I support your proposal. I think the examples should include all basic features people may need to use, not just select examples to explain the technical. Links from the documents to examples should be common. Much of the detail is concise for someone who already knows how to do it, but a single tiddler may demand already understanding 5-10 concepts. This makes it really hard to digest it as a first time user. It is a rare case of needing more verbosity without dumbing down. No concept should be without practical applications to see and view, this helps people who use learn by doing, to help them progress. Some of the great logic and design principals should be voiced rather than only found by induction after you gain an expert level of understanding.
I love TiddlyWiki and Version 5 but it is a steep learning curve to just do more than the surface level features. Thanks Tony On Monday, June 19, 2017 at 4:48:52 AM UTC+10, [email protected] wrote: > > 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). > > > > > *Proposed structure* > *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! > -- You received this message because you are subscribed to the Google Groups "TiddlyWikiDev" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at https://groups.google.com/group/tiddlywikidev. To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywikidev/684e4c2e-c06d-41c9-9da0-2483c151de41%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
