Use wiki for developer "meta" docs

[jcbhmr]

I like to use GitHub Pages for user-facing docs (things like JSDoc sites, an example playground, etc.) and GitHub wikis for developer-facing docs (things like conventions, layout, architecture, project history, etc.)

In order to do this in a way that works well with github/git PRs and stuff, it's nice to have a wiki/ dir (or docs/ or something) mirror to the GitHub wiki itself.

Here's a todo thing:

• Find a GitHub Action to deploy a folder to the wiki
• Use it
• Write some of those wiki pages

Wiki page ideas:

• How to create a template
• Styleguide.md (commit conventions, formatters, etc.)

related to #10 #8 #7

[jcbhmr]

I'm generally pretty OK at writing docs, so I can do the grunt work.

[jcbhmr]

Some ideas for GitHub wiki actions are:

• https://github.com/newrelic/wiki-sync-action bidi sync
• https://github.com/Andrew-Chen-Wang/github-wiki-action most popular
• https://github.com/spenserblack/actions-wiki up-and-coming; @jcbhmr is contributor (and is probs biased)

[jcbhmr]

You know, before I actually do this I should get a second opinion! Always get a second opinion 😉 That means you @eitsupi

Thoughts on the wiki dev docs idea as a whole? Good idea, bad idea? Alternative better idea? Hold off? Put it all in a big CONTRIBUTING.md file?

[eitsupi]

Thanks for listening to my input.

Actually, I am not too keen on using the wiki for that use.

• I find it difficult to discuss what to edit because there is no Pull Request and review mechanism.
• Markdown files in the main repository should be sufficient.

Also, since what we are dealing with here is a "Development Container," it is highly likely that the user is a developer, and I don't see much point in making a distinction between the two.

Thoughts on the wiki dev docs idea as a whole? Good idea, bad idea? Alternative better idea? Hold off? Put it all in a big CONTRIBUTING.md file?

We can also have a repository dedicated to documents and aggregate documents there.
Since this organization is likely to have multiple repositories with similar structures, it seems more suitable to consolidate documents into a single repository.

---

Deploying files from the main repository to the wiki is easy, and I see little need to use dedicated actions.
I set like bellow in the other repo.
https://github.com/rocker-org/rocker-versioned2/blob/d9dcc2caee7415b97cc14e39239da451798e25cd/.github/workflows/reports.yml#L102-L107

[jcbhmr]

Actually, I am not too keen on using the wiki for that use.

• I find it difficult to discuss what to edit because there is no Pull Request and review mechanism.
• Markdown files in the main repository should be sufficient.

🤪 This was actually the whole point of a GitHub Action like https://github.com/spenserblack/actions-wiki lmao: make it so the wiki stuff is in the source tree, but then it's "published" on each release to the GitHub wiki. This lets you do PR and other magic stuff (since it's in your source tree, just in a folder like wiki/*.md) -- sorry for the misrepresentation in the original issue.

Also, since what we are dealing with here is a "Development Container," it is highly likely that the user is a developer, and I don't see much point in making a distinction between the two.

🤔 I was thinking more along the mindset of a user, vs the mindset of a contributor (that probably is a better term) -- i.e. the wiki holds the convention docs for the repo, while the readme and GitHub Pages are the "showy" bits for users/consumers.

Sorta like I tried to do with devcontainers-contrib/features and its wiki: https://github.com/devcontainers-contrib/features/wiki

Does this clarify what I meant? 🤔 maybe you're right that this sort of info could be centralized or doesn't belong in a wiki.

---

Deploying files from the main repository to the wiki is easy, and I see little need to use dedicated actions.
I set like bellow in the other repo.
https://github.com/rocker-org/rocker-versioned2/blob/d9dcc2caee7415b97cc14e39239da451798e25cd/.github/workflows/reports.yml#L102-L107

You're right! At least, after I stared at it for 30s and figured out what was happening 😅 imo the short-and-sweet thing like this is easier to understand. Kinda like writing a function to compose multiple actions that could be manual. 🤷‍♂️ but yes you're right it is relatively easy and simple.

[eitsupi]

There is also a difference in that we cannot see the entire commit in the wiki on the web compared to the main repository (we can go back to the history of each page, or clone the wiki to local to see whole repo), so basically I feel that the main repository has more powerful features.

Of course I understand that a wiki has its advantages, but why not start with the .md files in the repository?

[jcbhmr]

Of course I understand that a wiki has its advantages, but why not start with the .md files in the repository?

Sounds like a good starting point! 🚀 Start small and grow from there.