Using wiki for documentation

[DRSDavidSoft]

Hi there,

Since the major improvements and moving to this organization, the docs have become a bit cluttered and they need to be re-organized, for example the original older part of the documentation needs to be updated to reflect the new changes, and the "Changes in this repository" section should be removed. Additionally, some new information could be added to each page, potentially making the whole README.md file longer. A new page for upgrading / breaking changes might be appreciated for users moving from the old repo.

For these purposes, I was wondering if using the Wiki section might be a good idea in order to organize the documentation, and have a page for each aspect of the library, instead of cramming everything in a single README.md file.

What are your thoughts?

[mathieucarbou]

With @me-no-dev we talked about documentation yesterday and yes it needs to be re-organised.
This is something that has to be done.

Using the WiKi is indeed a good idea because it would separate the doc from the project code and CI and will also allow to have sections, pages and will be more readable.

We would need some help though since there are more important things to take care first, so if you are willing to help for this task you are more than welcomed :-) Would be nice to have these nice diagrams and explanations you use to do in issues / prs 👍

[mathieucarbou]

I think it is right now... Could you please verify ?
If not, maybe I need to give you some permissions specifically.

[mathieucarbou]

Ok according to GitHub, I can add you as maintainer: https://docs.github.com/en/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/repository-roles-for-an-organization which will give access to wiki edits.

this is better than allowing public edits for everyone... Users could do mistakes we'll have to sort out / rollback

[DRSDavidSoft]

Okay, I am added as an contributor, I'll start making edits to the wiki! 🎉

[DRSDavidSoft]

@mathieucarbou Head's up, this will also give code push permissions to me, however I won't be doing any commits.

If the markdown pages require changes, I'll open a new PR in accordance to the contribution guides.

[mathieucarbou]

no worry ;-) we have branch protection rules in place. I think you should be able to edit the wiki without going through the PR process - that's one of the advantage of having a wiki.