Skip to content

Home

Jump to bottom
Margaret O'Brien edited this page Oct 25, 2018 · 13 revisions

LTER-core-metabase wiki

This is a test of how well wiki works for user documentation.

Background:

Copied the below from stackoverflow. But I do not see this in the git docs, so do not know the source, so it's likely to be one writer's opinion. https://stackoverflow.com/questions/32430473/what-are-the-main-functionality-differences-between-github-wiki-and-readme

  • Readme.md is the packaging
  • wiki pages is made for development/contributors documentation
  • gh-pages branch hosts user documentation (note: gh-pages are for building entire websites)

copied the below from: https://github.community/t5/How-to-use-Git-and-GitHub/Github-wiki-pages-vs-markdown-html-in-main-repository/td-p/2106

Wiki pages can be edited much more freely than files in the main repository.

They don't require a pull request or create a commit in the main repository.

By default anyone who is a collaborator can edit the wiki and the ability to edit the wiki can be made completely open separate from the main repository

Some people like this method of operation for documentation. Some people prefer keeping the documentation in the main repository (or in a documentation repository that is a peer of the main one). I'm in the latter camp because I like managing documentation using the same tools as everything else.

GitHub Pages isn't specifically a mechanism for editing or maintaining documentation, though it is often used for that as well. It is a system whereby one can easily publish the contents of a repository (not a wiki) on a website.

Conclusions (mob's)

Certainly if you want to build a website that's attached to a project, github-pages are a good option. but they come with overhead (clone, push - and Jekyll if you dive way in); gh-pages can be written in markdown, but organizing them is for coders. Wiki is probably has lower activation energy, and might be better for non-coders (has a built-in editor), but you will have fewer layout options. It looks like you can clone the wiki alone, see box at right.

things to figure out:

  1. how would you make the wiki prominent, if you want people to go there first. maybe just add a link to the repository description?
  2. is it duplicated documentation? e.g., when there is integrated code documentation, in R. or can you link the two?
  3. how to link into the repo itself.
Clone this wiki locally