What is the advantage compared to Azure Dev Ops WIKI?

[nbelyh]

You said you had that before... Just wondering what made you move from that to a new tool? Didn't quite get it from your article...

As of my experience, the problem with dev documentation is not the performance (the problem being solved by static generation), but that developers are simply too lazy to write (or update) it 😄

The simplicity of writing markdown text in DevOps wiki is SO MUCH EASIER compared to doing static site generation to SharePoint. You just click "edit", go to the online markdown editor, edit the page, click "save", done?

[estruyf]

Good point. The advantage is:

1. Using one system. Each department has their own tools they use, and all come with their own documentation/wiki. Like Zendesk, Hubspot, Azure DevOps, ... - We want to make it easier for everyone to find documentation in one place, and also make it easier when you stop using a tool, that you do not have to think too much of migrating documentation. Which we for instance right now have with the migration from Azure DevOps to GitHub.
2. Wiki is not source controlled in the same codebase as your project's code (like to use mono-repositories). What Doctor solves this, as you can now create for instance a docs folder in your code project, configure the doctor.json to publish it to a specific site. This way everyone can find it in your organization, and developers can easily reach it from within VSCode. For me, this is a major benefit.
3. Static site generators are indeed focussing on performance, but this tool focuses on uniformity. Makes it easier for the IT department which has to support and manage it. Permission management in Azure DevOps is not great.
4. Simplicity of writing markdown in VSCode is even better than in the browser. As you do not need to even open a browser.
5. Search is another benefit, as you would be able to easily search for all the information in one place, instead of all the repositories/wikis.
6. Easier when you working with different DEV teams, as you have one portal where they find all the documentation.

There are other advantages, but these are the most important ones.

PS: Congrats on opening the first discussion to the repository!

[jimmywim]

Wiki is not source controlled, and not part of the codebase

I swear it used to be!

[estruyf]

I meant not in the same codebase, but a separate project indeed. Will have to rephrase my sentence, too many thoughts rushing at the same time. 😁

[estruyf]

There we go, updated to what I actually meant to say 😂

[garrytrinder]

This depends on which wiki you use in Azure DevOps, there are two types, one is purely UI driven (provisioned) and the other which is Wiki as Code (published), the latter is taken from an Azure Repo and works "similar" to a static site.

See provisioned vs published Wikis in the docs for a comparison
https://docs.microsoft.com/en-us/azure/devops/project/wiki/provisioned-vs-published-wiki?view=azure-devops

[nbelyh]

IMHO, if a device "has more than three buttons" (c) then for common people (like me) it becomes "too complex to use" 😄

Also, just wondering who in sane mind would configure complex permissions for developer documentation wiki, and then maintain that?

Then just thinking how would you edit generated documentation online (in case somebody from sales department for example found a mistake) and propagate that back to the version-controlled repository (so that his changes are not overwritten)? Or if you found a typo? This "Sharepoint Wiki" can be edited only by the developer who has access to a specific source code repository, right - so you send email request to correct the documentation? 😄

[estruyf]

External users in your codebases, multiple divisions (product and consulting) - this makes the permissions complex very quickly.

The request to correct documentation is the same as when it would be on Azure DevOps. That is also more a developer platform. Our HR/marketing is not going to use that.

But you do not have to change your process if it works for you.