Github Wiki Request?

[pinuke]

I feel like a lot of the GH issues hare are often repeating. For example: #61

I feel like creating a wiki with a FAQ in the format:

Question/Error Message - try to format the Q:A in a way that is google-able Answer/Resolution

This may prevent the GH issues page from getting so big, and will at a minimum cut down on the amount of time spent replying to issues. I'd happily help maintain a GH wiki, if you'd like.

[pinuke]

What may even be a desireable feature is to have some kind of manifest file (.json?) for all of the possible error messages in the repo, so that we can auto-update the Wiki page via GH-actions.

Maybe in the format: error_manifest.json

{
  "ErrorTypeName" : {
    "message" : "Some error message that is used by the plugin",
    "solution" : "Some wiki text that is used by gh-actions to help generate the wiki page"
    //... some other error-pertinent data
  }
}

[Wiki_Article_for_the_FAQ].md:

# Answers to Common Questions

## Questions <!--generated by hand-->
### [Some Question]
[Some Answer]

## Errors <!--auto-gen'd by gh-actions-->
### [Some Common Error Messag]
[Some Solution]

[pinuke]

Here's a sample node.js script that you could use from within gh-actions:

const fs = require( "fs" )
let error_messages = require( "path/to/error_manifest.json" )
let wiki_contents = fs.readFileSync( "path/to/[Wiki_Article_for_the_FAQ].md" ).toString()

let handwritten = wiki_contents.split( "## Errors" )[0].trim()

// `map` over the .json entries to autogenerate the wiki
let generated = Object.entries( error_messages ).map( error_contents => {

  // Error's name is unused here. Doesn't have to be unused.
  // - I'll leave it up to you whether or not the wiki needs it.
  // - for: @brianpetro
  let [ name, error ] = error_contents 

  let heading = `### \`${ error.message }\`` // ### `[Some Common Error Message]`
  let body = error.solution                  // [Some Solution]

  return [ heading, body ].join( "\n" ) // Single-spaced separator between error heading and solution body

}).join( "\n\n" ) // Double-spaced separator between each error message

fs.writeFileSync(
  "path/to/[Wiki_Article_for_the_FAQ].md",
  // Double-spaced separator between handwritten, and auto-gen'd sections
  [ handwritten, "## Errors", generated ].join( "\n\n" ) 
)

[brianpetro]

@smartguy1196 thanks for your help with this.

I just started the discussion section https://github.com/brianpetro/obsidian-smart-connections/discussions

Do you think that might be sufficient?

If not, are there any other projects with wiki sections that you can point me to so I can get a better understanding of what that might look like?

Thanks for your continued contributions!

Brian 🌴

[pinuke]

Sample gh-action for pulbishing wikis: https://github.com/marketplace/actions/publish-to-github-wiki GitHub's about page for wikis: https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis

Wiki resource page with a list of popular wiki examples, tips/tricks, and stack overflow questions: https://github.com/MyHoneyBadger/awesome-github-wiki

[brianpetro]

Great resources, thanks, @smartguy1196 !

[pinuke]

@smartguy1196 thanks for your help with this.

No problem! I may not get a lot of extra freetime due to school and work to help out, but I feel like a wiki page should be easy enough for me to help maintain.

[brianpetro]

No problem! I may not get a lot of extra freetime due to school and work to help out, but I feel like a wiki page should be easy enough for me to help maintain.

@smartguy1196 Thanks that would be a big help.

I planned on using the Discussions section of GitHub. I like that it has more of a community feel than the wiki.

Can you start there?

Maybe with an FAQs post. Then we can pin/sticky it, and link to it from the README for newcomers.

[pinuke]

Hmmm... I don't think GH discussions is very automateable: https://github.com/marketplace?type=actions&query=discussion+

There's a GH Action for creating a discussion post: https://github.com/marketplace/actions/create-github-discussion

But not for auto-editing it as we expand the Error manifest. Though, if there is a GH web API for editing the disussion, I may be able to write my own GH Action for it.

A workaround would be to post the solution for each common error message as a separate discussion post, but as we can't (currently) auto-edit the posts, we will have to maintain them manually.

[pinuke]

Checking to see if there is an API for editing GH discussions. I think a good place to start is the source code for the gh action for creating a discussion post

[brianpetro]

I don't think we should be concerned with automating this. There aren't all that many FAQs.

Give it a little bit and I'll embed the GitHub issues, find FAQs via clusters, and let GPT-4 draft the discussion posts.

[pinuke]

The idea that I had was to embed the faqs into the errors as well as the wiki/discussion. So the "solution" and "message" properties can be read by both the plugin and the gh-actions bot for posting the docs.

In my experience, making docs automateable can be helpful later down the road when you want to scale the docs or scale the app. Having a bot lay the groundwork, then contributors make small tweaks can be very useful.

One way that I currently use this is to make my docs more available. I have a GH-Actions bot that copies my Docs folder to Just-the-docs GH-pages and my wiki. I'm also working on a GH-Actions bot that can handle a multijekyll gh-page (more than one jekyll site hosted from the same repo). That latter feature allows me to have a physically separated set of docs for developers and end-users (Ex: repo.github.io/devs and repo.github.io/docs would be 2 entirely separate Jekyll sites)

Though, for now, it may be good just to get a simple FAQ going, then have a bot maintain the FAQ later.

[pinuke]

Also, I found that the create-discussion gh-action is actually almost capable of doing edits to discussion posts: https://github.com/abirismyname/create-discussion/blob/5d67cb3bcc3c9cb96af6f08f476bc279051543b7/lib/discussion.ts#L16

Once, I learn the underlying API, I can get something nice going.

[pinuke]

Looks like implementing a bot will be pretty easy, if I fork create-discussions and change the load and update functions to match the save function: https://github.com/abirismyname/create-discussion/blob/main/lib/discussion.ts#L24

[brianpetro]

Though, for now, it may be good just to get a simple FAQ going, then have a bot maintain the FAQ later.

I think this is the way to go for now.

[pinuke]

Gonna scrub the issues for stuff that I'd want to put in the FAQ

[pinuke]

I think this issue can be closed out for now. If we have a new documentation or wiki request later down the road, we can reopen it.

[pinuke]

Dropping out of project. Thanks for the opportunity to contribute to an impressive open source project. Backing out, because I spend more time on this project troubleshooting than contributing.

I'm going to focus my time on school and my own projects. Have a good one Brian.

[brianpetro]

You will be missed! What are you studying? And what projects are you hoping to build?

[pinuke]

Robotics and Autonomous Systems Engineering at ASU.

I plan to continue my work on improving my Selenium management tools, so I can eventually finish my selenium plugin for obsidian.

I also have plans to rewrite AvaloniaILSpy in PowerShell. To get that one going, I need to finish my GUI library for pwsh. The lib operates similarly to PSAvalonia, except the GUI runs asynchronously in its own thread. I discovered the power of PowerShell runspaces and CSharp dispatchers a few weeks ago, and it has been an absolute game changer for PowerShell.

The problem with most pwsh GUI solutions at the moment is either they are antiquated or synchronous. PowerShell runspaces allow me to fix that by running GUIs in their own thread. I can then dispatch function calls on this second thread using CSharp thread dispatchers.

[brianpetro]

Sounds awesome! Good luck. Hope to see you around sometime in the future.

Brian🌴