Enhancement: Improve Teia Documentation Workflow And Appearance #1
Comments
|
I have forked the Teia Docs repo here, and since the upstream repo does not have "issues" enabled, I've enabled here so I can make the case for working on this. Now I would like to prepare a PR for setting up the bi-directional sync, but I'm faced with another hurdle in the fact that when you fork a repo, the hidden wiki repo is not forked along with it: So to test the wiki sync action, I need to first clone the wiki over to my fork, so looking at some suggestions on how to do this. |
|
So, I've played around with both methods, a simpler one direction sync and using the NewRelic GitHub Action. Both of these methods suppose you want to use a personal access token with a service account. Which would mean creating a service account. I did look at using the "secrets.GITHUB_TOKEN" special token but this doesn't seem to be working for pushing changes from the docs folder to the wiki repo. Well, there are more options to look at, there is another Action here: Seems more active, but lacking the bidirectional sync action. Also that action that wasn't able to push to the wiki should have failed, but I see someone has a fix for that here: I could at least validate that PR now. But might look at shopping the feature to other interested parties since NewRelic doesn't seem interested in this type of sync anymore. |
|
Moreover, this may be a more simple solution: |
|
I tried out the idea above of mounting the wiki repo as a submodule, but have concluded that is a bad idea: https://github.com/floydwilde/wiki-docs-submodule-test The thing I did like about it, was that it only required the secrets.GITHUB_TOKEN repo and not a personal access token, where the other solutions are mainly suggesting using a PAT and/or a service account setup w/ a long term PAT. I don't think this is a good option, it involves creating a dedicated account for managing that token which I would like to avoid if possible. I think one of the options where you setup a folder in the main repo and sync that to the wiki repo will be workable with the secret.GITHUB_TOKEN or some other option such as GitHub Apps. |
|
thanks so much for your help here floyd! i need to try my best to get my head around this so let me as a few qs
|
In the future, we would like to build on this change, taking the files that are now stored in the /wiki folder and using a static site generator like Docusaurus to make them more accessible to the reader. The overall effect, will be this: Approved members of the Teia Community will be able to use the GitHub wiki to edit files easily, or they can use the GitHub repository browser which is similar to the wiki interface for editing files. The repository browser interface provides the option of creating a PR (a branch) so that the edit can go through a peer review process, or make the change to the main branch which will publish it immediately. In the case of an editor wanting to fix a typo, or make some small correction, this is desirable. By taking the files out of the secondary wiki repository, and storing them in the main Teia Docs repo, we open up the possibility for the wider community to contribute in the normal way you would contribute changes on GitHub. You clone the repo, you make your changes, then you issue a PR. This is not currently possible, since the GitHub wiki is not intended to be used as a central document repository. It is meant to comment on a repo, not be a repo. Once this PR is merged, it will facilitate more collaboration on the documentation since the files will be accessible in the usual way. Eventually, I believe we will discover there is no purpose for using the Github Wiki UI, as NewRelic have discovered, we are using it for documentation due to a misunderstanding what the GitHub wiki feature is for. Our docs will eventually be stored at a url like docs.teia.art and people will go there to read documentation. For editing documentation, people will go to the GitHub Teia Docs repo, and edit files in the /wiki folder. Eventually, we will remove the documentation sync back to the GitHub wiki repo (look at NewRelic's Open Source Website as precedence) and we will remove the Teia documentation from that secondary Teia Docs wiki repo. Rather than storing our documentation there, we could then use this secondary wiki repo to provide instructions on how to update and maintain our documentation (not store it). |
|
One thing to remember is that the people contributing to the docs aren't necessarily devs and don't all have git expertise. Although the current wiki has several technical limitations, it is simple and easy to contribute. Also, up to now, the docs haven't gone through the same processes that the code does, which has mostly worked out fine. I don't have any particular thoughts against a new kind of wiki or doc repo. Still, whenever we take on something new for the community, we need to be aware of our limited resources and be confident that we can keep things running even when the original contributors of any new stuff have moved on to other things. Lastly, I thought somebody else was looking at changing how our docs are managed, but I haven't kept up to date on that; it would be good to make sure these attempts don't clash. |
|
Over the past few months, I've been reviewing the Teia documentation as it stands, it is in a not fit for purpose meta documentation repo which exists inside the GitHub Teia Docs, lets call it Repo Encirclement System. GitHub provides various enhancements to a basic Git repo. One of those enhancements is that it will create another repo for you, and a Wiki-like interface to that repo, so that you create documentation about what the purpose of the repo is and how to use it. Due to its convenience, The Teia community have been using this secondary documentation repo for the main purpose of creating and storing its documentation. What comes as convenience to some, is an inconvenience to others, unfortunately. For those people who wish to use a peer review process to make a significant documentation update, this option is not available to them. Secondly, for rendering the documentation in a more reader friendly format, the Github meta wiki repo is also not fit for purpose. Rather, using the /wiki folder, and events which occur to this folder, for publishing the wiki at a Teia.art url, like docs.teia.art, or wiki.teia.art, is more appropriate and flexible. This change takes the same advantage of the GitHub wiki feature we are using now, and restores the additional features that using GitHub to manage a central documentation repository is intended to have. |
no, i think it has always been floyd who volunteered to revamp the wiki. |
|
i thgink i agree with your assesment of the current situation and i am really excited to move this along finaklly towards a "real" documentation solution! all i want to make sure is that we can smoothly transition and make edits fun and accessible to the community (ideally at some point even allowing input from all members/users |
|
Yep, I think you will see things were just kind of blocked up due to a misunderstanding of how what the "GitHub Wiki" feature was designed for. Now that we are unblocked, we will begin to see a lot more contributions to the wiki. I'm about to contribute the first in a series of more updates, to actual documentation. |
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:
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:
And some experimentation here, adapting the wiki files for use w/ Docusaurus:
The text was updated successfully, but these errors were encountered: