some improvements to the wiki documentation

[anarcat]

hi!

so as suggested in #93, I have pushed my changes to the wiki in a separate repository here:

https://github.com/anarcat/pat-wiki

you can see the latest changes here:

https://github.com/anarcat/pat-wiki/commits/master

i have more ideas and suggestions of things to improve there, but let's see how this one goes before I got crazy. :)

PS: i do think it would be better if the wiki would be editable to all git-hubbers. a wiki that is not editable is not really a wiki, to be honest. worst that could happen with the wiki publicly writable is vandalism, and that's easy to revert with git, and even then, users are not anonymous and could get blocked, so i think that's very unlikely. that actual worst thing that could happen is no one would contribute, but that's already the case... ;)

[martinhpedersen]

Thanks, I have merged the changes.

Yes, I can agree to some extent that the wiki should be editable to all git-hubbers. However, since it is the location of the "official documentation" I think it is reasonable to have a minimum amount of discussion before changing it. Unfortunately, this is the only way to enforce such a workflow with GitHub hosted wikis.

Do you think it would help to write a section about it in the Wiki or https://github.com/la5nta/pat/blob/master/CONTRIBUTING.md file? I really do want people to easily be able to suggest changes and additions to the wiki.

[martinhpedersen]

Closing this issue, as the changes was merged. But let's continue the discussion here anyway, please.

[anarcat]

Thanks, I have merged the changes.

awesome!

Yes, I can agree to some extent that the wiki should be editable to all git-hubbers. However, since it is the location of the "official documentation" I think it is reasonable to have a minimum amount of discussion before changing it. Unfortunately, this is the only way to enforce such a workflow with GitHub hosted wikis.

my experience with documentation and wikis is that the entry barrier should be as small as possible, because it's already really hard to get people to contribute documentation. the whole point of having a separate wiki on github is that you can have a different, easier workflow for contributors.

if you want to have the usual issue/PR/review workflow for documentation, why put the documentation in a wiki at all? why not move all the documentation inside the source code directly? that way you get the normal issue/PR/review workflow you are familiar with and documentation gets shipped with a source code, which is a huge plus. then the documentation gets rendered inside github directly or you can hook it into github pages or whatever to make a publicly readable version. i often use readthedocs.org for that purpose.

Do you think it would help to write a section about it in the Wiki or https://github.com/la5nta/pat/blob/master/CONTRIBUTING.md file? I really do want people to easily be able to suggest changes and additions to the wiki.

definitely. but i would argue, again, that if you want people to easily be able to suggest changes to the wiki, you should just untick that box. ;) otherwise, i gotta say it's actually easier to send pull request to markdown files part of the source code than the janky "wiki fork" workflow. :)

thanks for the merge!

[anarcat]

i noticed that the wiki is now writable, thanks! :)