I put together https://github.com/fordsfords/kb_thingie as a primitive Knowedge Base. For a real implementation of it, see https://github.com/UltraMessaging/um_kb

In putting together the UM KB, I submitted the home page and the index to be crawled. It was successful, and you can google search and find those pages. However, for some reason, Google is not following the links on those pages (especially the index) and therefore cannot find anything on the content pages.

I don't have time to figure out why, so I've been using https://search.google.com/search-console/ to simply request a crawl on each page. As new pages are added, this should be repeated.

Previous Content

A knowledge base (KB) is basically a set of related articles comprising the collective wisdom of a product or service. A common implementation of a KB is a wiki, but there are also specialized KB systems out there that perhaps do a better job of searching, indexing, and formatting in a consistent way.

You could argue that Wikipedia is a giant KB, but I think of a KB as being much more narrowly focused. GitHub Wikis allow each repo to have its own wiki, so that would seem to be a natural way to implement KBs. But I wanted to do some higher-level thinking about KBs before settling on the GitHub Wikis.

(This assumes that you have a team of engineers who would want to add and edit KB articles that are available to the general public.)

• Does it need /version/ control? I don't think so. Certainly, the whole KB is not versioned. One article might be versioned (v0.9, v1.1, v2.0), but really how necessary is that? With s/w it is necessary b/c if somebody has a problem, we need to be able to ask them what version it is so we can bring up the state of the source tree as of that version. But I can't think of an analog for KB articles. I guess a KB article could have some sample code associated with it, so an article version still might be useful, but better than the code itself have a version. I would prefer real code (i.e. modules, not fragments) be as separate files in a repo. So I don't think it needs version control, other than being able to get at earlier versions of an article (history).

• Do you want it crawled by search engines? If so, it can't be in the wiki. Github wikis are not crawled except under certain circumstances that I'm not likely to ever meet. So forget the wiki for anything you want searchable.

• Having a web-based method for creating/maintaining it can be nice. It sets a low barrier to entry for maintainers, but also suggests that a "build" step might be undesirable. Also, web-based text editing is often much less desirable than a "real" text editor (like "vi" or "emacs"), so having both methods available is desirable. Also, it is sometimes handy to use scripting ("sed", "perl", etc.) to automate mass updates, which suggests the entire KB being available in file form.

• Note that .md files are not rendered in gh-pages. If you want it in markdown, it needs to be in a repo. But google does not appear to index .md files in a Github repo. So to be googlable, you must either have the master source in the form of HTML (and potentially use an HTML editor for ease of use), or use some translation step to go from md to html (this is what "kb_thingie" does), which is an unfortunate build step.

• I initially thought about using a GitHub wiki basically for the maintainer interface, and having a script that extracts the wiki files and updates a normal repo for user access. This solves the search engine issue.