search

backdrop-contrib / domain

A domain-based access control system for Backdrop CMS
https://backdropcms.org/project/domain
3 stars 5 forks source link

Move documentation in text files to wiki #27

Open izmeez opened 1 month ago

izmeez commented 1 month ago

There is a lot of documentation in text files in the module repository such as README.txt INSTALL.txt and INSTALL_QUICKSTART.txt that can be copied to the wiki.

The text files have been copied to the wiki with amending as needed. The wiki pages should be reviewed and if confirmed the text files in the repository may be removed.

izmeez commented 1 month ago

The wiki Home needs to be deleted and replaced with 1. Domain module wiki as the starting page.

I think, initially, I did copy the new text into the existing home page but when it was saved a new page was created and a stub left of the original page, may be just the title. If anyone knows how to delete the page and reset the home link?

stpaultim commented 1 week ago

I am in agreement that the WIKI is probably a better place for this information and easier for more people to contribute.

I would organize and label the wiki pages a bit better. Maybe put all of these new pages as childen of a parent page that will help people navigate them better. Right now, I think we have one very long list of wiki pages and it's hard for me to find what I'm looking for.

izmeez commented 1 week ago

@stpaultim Can you provide a link to an example of a wiki with the structure you are proposing? I deliberately avoided nesting pages as parent/child to reduce navigation and visibility of the topics.

Also, I am not yet convinced that it is better to have this documentation in a wiki rather than included with the module, possibly in a /docs folder. One problem I have encountered is that it does not seem possible to search the wiki for keywords. Maybe I need a pointer on how to do that? If the docs are part of the module then tools like VSCode will handle this easily.

yorkshire-pudding commented 1 week ago

@izmeez - it is possible to do both. That is what I have done in Bee. There is a GitHub Action in bee that updates the wiki whenever the files in the /docs folder are changed. I agree that wikis are not possible to search. Something else, which I'm thinking about for bee (that could also work here) is https://about.readthedocs.com/ - this would also work from the /docs folder

izmeez commented 1 week ago

@yorkshire-pudding I took a closer look at the docs and wiki for Bee and really like that. I would be in favour of a similar approach for the domain module.

yorkshire-pudding commented 1 week ago

@stpaultim @rudy880719 @sudipto68 Do you have any thoughts on the proposal to move the wiki to a docs folder with a GitHub Action to push changes to the Wiki?

Here are the pros and cons I outlined when I did this for bee (not that anyone responded to that):

Pros

  1. Allows wiki changes to be drafted as part of a pull request
  2. Wiki can be drafted using an IDE which will be more user friendly than the edit window for long pages.
  3. Less likely to forget to do wiki changes after the merge if need to be done at the same time
  4. Ties documentation changes to changes in functionality, behaviour, or any other changes so the docs in a given version installed would match the functionality in that version.
  5. Would make it easier to add screenshots to the wiki as could have subfolder for images
  6. locked down wikis can be indexed by Google, although we need a few more stars

Cons