floydwilde / teia-docs Goto Github PK

GitHub Wiki and it's Limitations

The Teia-Docs GitHub repo exists to collect documentation that is project-wide, and doesn't relate to any code which is actually in the 'Teia-Docs' repo. But, the GitHub wiki feature is meant to collect documentation about what a specific repo is for, and how to use it. It creates a hidden 'sub' repo, which is just a regular git repo, but it is not exposed to all the nice enhancements GitHub provides for a git repo. It's meant to be out of the way, and to describe and document the main repo. The ability to create PRs, the main feature that is missing from a GitHub wiki, which has been discussed (for years) in various places:

• https://stackoverflow.com/questions/10642928/how-can-i-make-a-pull-request-for-a-wiki-page-on-github
• https://nimblehq.co/blog/create-github-wiki-pull-request

For the "Teia-Docs" repo, the documentation is the main event, and the wiki is only utilized for convenience to encourage quick updates and faster editing. We would prefer to use GitHub Pages, which would provide a more user friendly interface for general readers of the documentation.

Proposal for Workflow Enhancement

To address this limitation, we propose moving the files that are being edited within the GitHub wiki to a dedicated location within the main repository. By doing so, we can leverage the full functionality of GitHub for version control, collaboration, and organization. Additionally, we suggest utilizing a GitHub action to enable bidirectional syncing. This action would synchronize any edits made in either the main repository or the wiki, ensuring that the documentation remains up to date.

By centralizing the editing process within the main repository, we can take advantage of the convenience and benefits offered by GitHub while maintaining a cohesive and synchronized documentation system. This approach will also help mitigate the risk of data loss, as file deletions in the wiki will not be synced, but it is possible to delete a file by editing it within the repository where the files reside.

Retaining Collaboration and Utilizing GitHub Pages

In addition to the advantages mentioned earlier, adopting this approach allows us to keep the collaborative benefits provided by the GitHub wiki. By maintaining the wiki as a secondary documentation resource, we make it more convenient for team members to contribute and collaborate on the content. Simultaneously, we can take full advantage of the customization options and domain mapping capabilities offered by GitHub Pages.

The need for a better workflow grew out of interest in using a static website generation tool called "Docusaurus" in this PR:

• teia-community#1

And some experimentation here, adapting the wiki files for use w/ Docusaurus:

• https://teia-community.gitlab.io/teia-staging-docusaurus/