Using the wiki for core documentation and related issues

@wolftune and I would like use the wiki for our core documentation (values, economic theory, market research, goals, mechanism, etc)[1] and make the wiki Gitlab project the place for tracking issues at that level (the main motivation — right now those issues have no home).

Before we fully embrace this, we’d like to get a little buy-in: @team if this sounds good, please acknowledge this post in some way. If you have questions or concerns, you can bring them up here or in Wednesday’s meeting. If you want more context, read on.

Background / Motivation

Aaron, Michael, and I have been discussing potential updates to the crowdmatching mechanism. So far we’ve had a very verbose, open-ended discussion. Now, as we start to narrow down towards specifics, we’re ready to share a more concise version of our thoughts with the team.

We planned to start that discussion by writing a post here on the forum, but ran into an issue: There isn’t really an appropriate category, either here or on GitLab (for tracking this task: writing the post). The closest is #clear-the-path:design, and while that would be technically correct, it’s a different scope of design; it’s really about the “design” of the platform overall, since it touches on topics like our mission and business plan.

Aaron and I talked about this, and decided the best place to create an issue on GitLab is probably the [wiki repo], since a lot of its content is already closely related. And if we’re going to use the wiki for these sorts of issues, it would be better if other stuff we’ve just dumped there to other, more suitable locations (drafts to GitLab issues, meeting notes to their own repo, etc). This has the added benefit of making the wiki’s search more useful — right now it has a lot of clutter, mostly due to meeting notes.


  1. We’d shift other types of content to different locations; stuff like team member profiles, onboarding info, and meeting notes, is there because the wiki has been acting as a catch-all for stuff with no other home, not because it’s where that content belongs. This would be done gradually over time, not in a big proactive reorganization (we’ve done enough of those already…). ↩︎

2 Appreciations

or maybe just to the governance repo, that’d be simple enough.

Only issue of moving them is maybe a redirect would be good since there might be links to them. Same with other things moved out of wiki, keeping links from breaking is a concern. But probably very few links to meeting notes anywhere really.

Especially for people searching the wiki for other things, the meeting notes are noisy clutter.

I would expect gitlab.com/snowdrift/wiki/issues to be issues about the wiki.

Can you give examples of “issues at that level”? It’s hard for me to have an opinion otherwise.

This came up around https://gitlab.com/snowdrift/wiki/-/issues/26 which is about planning, presenting, discussing, and then potentially deciding on a change to the crowdmatching mechanism.

I don’t want to discuss that itself here, but if we reach consensus, the outcome of such a change would lead to several changes:

  • update the mechanism wiki page
  • code issues to work with an updated approach
  • design changes for the front-end and explanation parts of the main site

Since the issue is high-level and touches many different areas of the whole project, it didn’t seem like a code-specific issue, mainly because the current tasks are about meeting and presentation planning (there’s not yet any decision to do anything otherwise). Maybe those should go in the governance repo though.

The wiki-issues perspective is that the wiki is the primary place the crowdmatching mechanism is described in detail.

Thanks for the example, it makes a lot of sense!

In my more recent experience, high level planning of this sort is best expressed in prose. So my recommendation would be to reject the thesis of the original post (“use the wiki more exclusively for core documentation”), and continue to use the wiki for tracking initiatives, milestones, and development sync-points across the entire organization.

The tension with issues is that they provide constraints that are very useful for tracking individual tasks, but that get in the way of providing a holistic overview. At best you can create a tree of issues, perhaps with some cross-links. This is usually inadequate for describing the mutual/soft/eventual (take your pick of relevant adjectives) dependencies that exist at higher planning levels.

Using prose (and pictures!) in a wiki is a better fit for developing human-comprehensible descriptions of these ideas. It is even entirely appropriate to have todo-lists in the wiki, particularly when the items are either very large (“redesign the about page”) or very small (“update this very paragraph”).

Some constraint is good, but it has to be deployed consciously, not provided by tooling. In particular, try to keep discussion outside the wiki, and treat it as the place to track the outcomes/decisions themselves.

2 Appreciations

This is indeed a better wording! Added the qualifier that the proposal is about something the wiki should be for, independent of deciding things it should not be for.

Marking this as the “solution” for now. However, I think there’s a next-step of capturing this (well, similar wording) in a clearer way in more permanent places both on the wiki itself and in the description of the wiki Gitlab project.