3 ms·

I don't understand the utility of the wiki. Markdown is already rendered in the repo and can live next to the code. Meaning that merge requests can update both

I don't understand the utility of the wiki. Markdown is already rendered in the repo and can live next to the code. Meaning that merge requests can update both the code and documentation at the same time. And GitLab / GitHub have embedded editors that allow you to edit the markdown files using from the browser, just like a wiki. Basically the only thing that is left is that the wiki can be edited without supervision.

OJFord 7y ago
I find they're rarely good, but I can see that having them live alongside code is good sometimes (as you say) but not so great when it needs to be changed independent of the code around it and you have a load 'fix markdown rendering' or 'fix typo' commits.
- mikepurvis 7y ago
  That feels like a failure of the tool/workflow— when you use the web UI edit button, it should put your edits on a branch for review, and make it easy to make further edits/corrections and then squash all of the piddly fixes into one big change at the end.
shantly 7y ago
Non-programmers are more comfortable in the Wiki. And it's probably safer to keep them there anyway, and edits can be allowed there with fewer safeguards. Then again I'm not sure how many non-technical folks are willing to dig into GH anyway. I've heard Issues & friends called "too confusing" for "non-technical" folks, in favor of Asana and Jira, of all things. Huge WTF from me since I'd say the opposite is strongly true regardless how "technical" one is, but that's the perception I guess.
mikepurvis 7y ago
My company uses GitLab/Jira/Confluence, and two super-important features that make Confluence a winner in my mind are a) a way better story for media embedding (including photos and random uploads like PDFs, but also rich/interactive media such as LucidChart and rendering ticket lists from a Jira filter), and b) the inline discussion/annotation framework that lets you tag/nag people, ask for clarification, etc. A big part of inline discussion is that it's an instant marker for later readers that the content may not be up to date or is under discussion/review, whereas a Markdown file in some repo can have a ticket filed against it, but there's nothing in the repo that alerts a later reader to the existence of that ticket until the problem is actually resolved. I've always been an advocate for the "markdown in the repo" scheme with CI-generated Sphinx (or whatever) docs, but these features have really won me over to the standalone wiki at least in some cases.
unilynx 7y ago
Fortunately, you can disable the wiki (and snippets!) on a per-project basis in at least Gitlab. Which is what we do on all our projects to ensure that everything goes through a single versioning flow.
paulddraper 7y ago
> Basically the only thing that is left is that the wiki can be edited without supervision. Yes, that's a significant difference. Publically contributed information (Wikipedia, Stack Overflow) can be quite good. --- Another difference is that the wiki is not versioned with your code. (An entirely separate repo, but stil logically connected with the code repo.) HEAD of wiki is documentation for version 1, version 2, version 3, etc. of your code. That may be a good thing; that may be a bad thing.

OJFord 7y ago

I find they're rarely good, but I can see that having them live alongside code is good sometimes (as you say) but not so great when it needs to be changed independent of the code around it and you have a load 'fix markdown rendering' or 'fix typo' commits.

mikepurvis 7y ago
That feels like a failure of the tool/workflow— when you use the web UI edit button, it should put your edits on a branch for review, and make it easy to make further edits/corrections and then squash all of the piddly fixes into one big change at the end.

shantly 7y ago

Non-programmers are more comfortable in the Wiki. And it's probably safer to keep them there anyway, and edits can be allowed there with fewer safeguards. Then again I'm not sure how many non-technical folks are willing to dig into GH anyway. I've heard Issues & friends called "too confusing" for "non-technical" folks, in favor of Asana and Jira, of all things. Huge WTF from me since I'd say the opposite is strongly true regardless how "technical" one is, but that's the perception I guess.

mikepurvis 7y ago

My company uses GitLab/Jira/Confluence, and two super-important features that make Confluence a winner in my mind are a) a way better story for media embedding (including photos and random uploads like PDFs, but also rich/interactive media such as LucidChart and rendering ticket lists from a Jira filter), and b) the inline discussion/annotation framework that lets you tag/nag people, ask for clarification, etc. A big part of inline discussion is that it's an instant marker for later readers that the content may not be up to date or is under discussion/review, whereas a Markdown file in some repo can have a ticket filed against it, but there's nothing in the repo that alerts a later reader to the existence of that ticket until the problem is actually resolved. I've always been an advocate for the "markdown in the repo" scheme with CI-generated Sphinx (or whatever) docs, but these features have really won me over to the standalone wiki at least in some cases.

unilynx 7y ago

Fortunately, you can disable the wiki (and snippets!) on a per-project basis in at least Gitlab. Which is what we do on all our projects to ensure that everything goes through a single versioning flow.

paulddraper 7y ago

> Basically the only thing that is left is that the wiki can be edited without supervision. Yes, that's a significant difference. Publically contributed information (Wikipedia, Stack Overflow) can be quite good. --- Another difference is that the wiki is not versioned with your code. (An entirely separate repo, but stil logically connected with the code repo.) HEAD of wiki is documentation for version 1, version 2, version 3, etc. of your code. That may be a good thing; that may be a bad thing.