Thoughts on GitHub, Issue Tracker, Gollum Wiki, etc.

• Playing with Github wiki (Gollum) features
• WORKAROUND: linking between GitHub issue tracker and wiki

1. 1. 1. Bitching

... I thought that speech recognition wasn't working, but it seems that something in the speech recognition system had stopped.

As I start using the GitHub wiki I'm impelled to make many complaints, marked as "GitHub wiki bitch" and similar such.

1. 1. 1. Q: is there a page tree display in the GitHub wiki?

Not AFAICT. So I've started reviving for the umpteenth time my old scripts to do this, cloning or updating the wiki (thank goodness it is in git), running the script, and then pushing back.

1. 1. 1. Link syntax on the GitHub wiki (Markdown)

CONCLUSION:

• I prefer to use Markdown syntax, because it knows how to color links to pages that do not exist yet red.
• I would like to use AsciiDoc, but the AsciiDoc link/cross reference syntax is clumsy

GitHub Wiki bitch:

• not only does it seem that links break when their target page name changes
• but there doesn't seem to be auto complete when using the pseudo-GUI link facility?
• I guess I've been spoiled by Confluence
• but at least I'll have this when I returned to editing these things in Emacs

1. 1. 1. No redirects in GitHub wikis? not even in MediaWiki?

MediaWiki redirects are similar to symlinks. They are apparently not supported on the GitHub wiki.

Probably not needed for the GitHub wiki's main markup language, Markdown, but it is a pity that they are not provided for the MediaWiki Markdown that is also supported by the GitHub wiki.

As I have said many times, the ability to have something appear under multiple names is really important.

1. 1. 1. Q GitHub Issue Tracker: want 2nd line quick summary, below title

E.g. in https://github.com/AndyGlew/Ri5-stuff/issues/2

The issue title started as

• Verify that the recommended partial instruction completion loop constructs for CMOs operate correctly if optional prefetches or hints are treated as NOPs.

But I like having a quick status at the top

• A: not for the POR [hi,lo] form. The nbytes forms could work, but are not POR

Placing the status in the title sucks

• Verify that the recommended partial instruction completion loop constructs for CMOs operate correctly if optional prefetches or hints are treated as NOPs. (A: not for the POR [hi,lo] form. The nbytes forms could work, but are not POR)

I really want a one line title, and a one line quick summary.

Sure, the information should be somewhere in the comment history. But I'd like to see it near the top, for standard reports. Having to search for comment history sucks, especially if somebody wants to add comments after the final resolution is been decided. As in all things, it is possible this issue tracker has this feature, and I may not have found it yet.

1. 1. 1. GitHub issue tracker links to GitHub wiki are inconvenient

Enough said

1. 1. 1. Copy/paste screen-snips into GitHub issue tracker

Like, if you want to report a bug in formatting, that you can only see in the screen-snipper.

Yeah, I'm to blow the lazy to put into a file and then upload link to it. Copy/paste is a heck of a lot faster, and produces more high-quality bugs than having the level of indirection.

IIRC you can copy/paste into the GitHub wiki. Why not into the issue tracker?

(Yeah, yeah, file size, malware, ...)

1. 1. 1. GitHub issue tracker not off-line?

I'd like to be able to create issues off-line just like I can edit the wiki and source code.

Attaching Diagrams and Other Files on Github

I think diagrams are really, Really, REALLY important for computer architecture.

For that matter, I think comparative tables are also important. Although one can create tables using the GitHub wiki, other table editors are much better. Starting off with spreadsheets like Excel or Google sheets, but also extending to other wiki tables where you can sort and rearrange fields.

Unfortunately, one cannot attach special file types like images directly to the GitHub wiki. One can link to images, e.g. stored in the actual repository. But that loses the benefit of version control within the wiki. One must rely on the version control within the repository. Which is not necessarily in sync with the wiki.

Anyway:

• https://help.github.com/en/github/building-a-strong-community/editing-wiki-content#adding-images

Here's a first attempt at linking to shared LucidChart diagram:

• https://www.lucidchart.com/documents/view/1bc0ecd7-846c-4973-b81f-a13c19cdc831

  * note: needs prettification
    * [[Glew wish for links with both numeric ID and human readable name]]

BKM: special characters like hyphens in GitHub wiki page titles