added glossary, details on new files from templates

ofossum commented 2 years ago

Added the glossary.md and did some changes to see how editing and Markdown-Wiki works in Github.

ofossum commented 2 years ago

Updated the documentation with some details on choosing templates and added an image

dpolivaev commented 2 years ago

Hey, why have you closed it? Don't you want it to be merged?

ofossum commented 2 years ago

Sorry i closed the pull request -- i'm quite new to github and figuring stuff out, so my actions might seem a bit… weird. :D

dpolivaev commented 2 years ago

I looked at this PR again. I am afraid it is not polished enough to be useful. @macmarrum how do you see it?

ofossum commented 2 years ago

Hi, i'm sorry for messing around with so many commits adding testfiles etc. - i was figuring out git a bit. I'll try to squash these together, if this is what holds this PR back. If you have more details on what would make it more polished for merging, feel free to give me feedback on this.

dpolivaev commented 2 years ago

I do not care about the number of commits. I care about the content quality, systematics and completeness.

https://github.com/ofossum/wiki/blob/main/customizing-freeplane.md: this page does not describe how to customize Freeplane. It just says where the user configuration directory can be found at some OS and say nothing about the rest. The content is neither complete nor matching the page title.

https://github.com/ofossum/wiki/blob/main/glossary.md: this page called glossary contains just one entry. I am not sure if the wiki needs a glossary, but I am sure that glossare containing just a single item is not a glossary.

https://github.com/ofossum/wiki/blob/main/templates.md: this page is probably the best part of the contribution. However it covers only a small part of information related to templates. It does not describe followed and associated mind maps which should not be missed in any introduction to templates. It does not cover styles. It has a link to wiki page called Styles but opening it ends up with a 404 error.

So all in all I am not satisfied with the quality of this contribution and I decided to reject it to save my time. Polishing it is likely to cost me too much effort. I am sorry.

dpolivaev commented 2 years ago

If you want to try submitting other PRs, you are welcome. If you make them small and consistent I would be happy to merge them.

ofossum commented 2 years ago

Okay, just to clarify my perspective on this work and contribution to the wiki:

the "Wiki" is far, far from complete. I think it's better to make this Wiki grow step by step, adding parts and making small contributions than adding a whole chapter which is already finished. This is also what you said in the end:

If you make them small and consistent I would be happy to merge them.

While writing, i oriented my work on the sections written in the README.md. This is the first file and "main page" when you open the wiki. All the links there were already in place, but currently lead you to files not yet existing and throwing errors (404).

Hopefully this explains the points you mentioned:

https://github.com/ofossum/wiki/blob/main/customizing-freeplane.md: this page does not describe how to customize Freeplane. It just says where the user configuration directory can be found at some OS and say nothing about the rest. The content is neither complete nor matching the page title.

The customizing-freeplane.md did not exist and there was no content at all. Yet, the first page (the README.md) linked to that page. So i put some content there. Under customization i'd expect something like "where is my user-defined content?" -- so this is something what was already a clickable something getting you nowhere, for which i added a section in the given destination. Now there would be at least some starting point for more content, falling under "customization". And if you were new and took a look on this page, you can immediatly see that something is missing.

https://github.com/ofossum/wiki/blob/main/glossary.md: this page called glossary contains just one entry. I am not sure if the wiki needs a glossary, but I am sure that glossare containing just a single item is not a glossary.

I like the a idea of a glossary but if there should be none, then it's fine for me.

https://github.com/ofossum/wiki/blob/main/templates.md: this page is probably the best part of the contribution. However it covers only a small part of information related to templates. It does not describe followed and associated mind maps which should not be missed in any introduction to templates. It does not cover styles. It has a link to wiki page called Styles but opening it ends up with a 404 error.

Since i won't cover stuff i'm not rally familiar with (styles), i didn't touch the styles.md, which was linked in the README.md as well but gives you error 404. This is not satisfying (also for me) -- but when there is no content, then it's not my fault there is nothing to see. As i said: these links already existed and the overall structure of the Wiki-pages was already there -- so i won't touch them, unless i have a very good reason.

So all in all I am not satisfied with the quality of this contribution and I decided to reject it to save my time. Polishing it is likely to cost me too much effort. I am sorry.

Well, that's okay. I believe, the README.md is made by somebody who already put a bit of thoughts and time in to do. Right now, there is no content at all in most of those pages, even if the wikis main-page (README.md) shows you a TOC and possible content: the wiki mainly just give you an error 404 for nearly everything. I'd like to contribute while sticking with that given structure, adding those pages and filling them with information bit by bit, which then could be build upon.

Since it's really obvious that there is a lot to be desired, those wanting to contribute can just add small parts, when there is none -- like you also said you would accept as a PR.

dpolivaev commented 2 years ago

Actually, the problem is that nobody cares about the documentation. I have neither skills nor capacity and nobody else does it either. Readme was written by a guy who promised to finish it but disappeared. Nobody else joined to replace him.

To be honest I do not even want to review documentation contributed by others. I think I shall abandon the freeplane wiki project soon.

dpolivaev commented 2 years ago

I started discussion https://github.com/freeplane/freeplane/discussions/305 about it.

quickfold commented 2 years ago

Documentation PRs should never be rejected for incompleteness or other writing errors. Documentation is not code. No documentation is ever 100% complete or perfect. I am amazed that @ofossum is getting any feedback other than thanks for their PRs.

Actually, the problem is that nobody cares about the documentation.

Actually, many people care about the documentation. You are just not one of those people.

I have neither skills nor capacity and nobody else does it either. Readme was written by a guy who promised to finish it but disappeared.

Readme was written by me. I did not "disappear" but spent a LOT of time trying to figure out and get you to accept a model of collaboration that would allow you to work with others in a way that did not risk wasting their time. We were unable to come to a mutual agreement about this, which is why I stopped developing the wiki.

Nobody else joined to replace him.

You might consider that this is not just a random unfortunate event but the result of how the documentation has been managed by you. If you don't care about documentation, you can let someone else manage it and not worry about evaluating it. If you want control, then you have to care about the documentation and manage it if you want it to exist. If you want total control, but don't care about documentation, then you won't have documentation, which is the current situation and will not change unless one of these other factors changes.

freeplane / docs

added glossary, details on new files from templates #8