Hi Tony and thanks for your support/feedback! I agree with you. There are many problems with the current documentation that are a source of confusion an frustration. I have planned to cover the problems with the content in the second part. In case my proposal will not be accepted, I will make an alternative documentation system on my site anyway to demonstrate my ideas. But to have a really useful documentation and put things on the move we need to raise our voices. So I invite you and other interested people to share your opinion/proposals here and also on the GitHub issue dedicated page: https://github.com/Jermolene/TiddlyWiki5/issues/2912
Thanks Adrian On Sunday, June 25, 2017 at 12:03:42 PM UTC+3, TonyM wrote: > > 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/621aaa01-534b-4efa-b3ed-b71f1d0d337f%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
