In most companies I've worked for only part of the contibuters to the company's Wiki were developers. What about Product Managers, BizDev people, etc?

Do you expect everyone at the company to use git and work with markdown? (Don't get me wrong, I wish everyone did. But knowing people in these roles makes me think this would never happen)

I may be in an unusual position of being able to dictate this but I always push for non-coders to use git and markdown... design assets are checked in to a repo, blog posts use markdown and are pushed to a Netlify site, marketers can tweak language and images directly in our Vue app (partly chosen for Vue's fantastic accessibility), etc.

TBH I have not pushed non-coders to document stuff in git / markdown, only the developers do that.

Free, friendly tools like Github desktop, VS code, Netlify CMS help a ton. It also helps that marketers, designers, product managers are all technically inclined positions, where hiring smart people pays off.

There's a tradeoff as it takes more time to preach and teach the use of these tools, but I see it as a good investment for workflow and in people. Being able to wrangle git is a great skill!

This would be insanity in a mono repo. A developer would have to look over every PR to make sure some critter from the marketing department didn't accidentally change an important bit of code.

1) You'd setup a Policy based on directory or Regex of files and organize your monorepo so that only the people that need to see the PR would. Use your tools to your advantage.

2) It really depends on your culture at your company, having open access to view and change the code from marketing to submit small PRs or possibly move to development. Or submit blog posts or spelling fixes to the marketing website can make for a great team.

3) This adversarial "Critter", Developers > Marketing view makes for a very toxic workplace. Marketing is a skill-set just like development, without marketing or sales there is nothing develop, without development, there's nothing to sell.

> You'd setup a Policy based on directory or Regex of files and organize your monorepo so that only the people that need to see the PR would. Use your tools to your advantage.

Hard to catch everything

> It really depends on your culture at your company, having open access to view and change the code from marketing to submit small PRs or possibly move to development. Or submit blog posts or spelling fixes to the marketing website can make for a great team.

I'm all for open access, but systems should have safety rails to stop people from making mistakes. This is why we have the PR process in the first place. If you have non-programmers approving PRs created by other non-programmers into repositories that have mission critical code, then you're really just asking for trouble.

> This adversarial "Critter", Developers > Marketing view makes for a very toxic workplace. Marketing is a skill-set just like development, without marketing or sales there is nothing develop, without development, there's nothing to sell.

My position actually straddles product and development, so I spend much more time with marketing types than developers these days. They're fine people, but they aren't as patient and detail oriented as developers and lack awareness of the dangers of certain actions. I've seen them do all sorts of crazy stuff that would throw the security team into an absolute fit if they found out about it.

That's something your ownership and CI systems catch, and is a prerequisite to use a monorepo sensibly in the first place.

The ownership system ensures a per-subpath commit/review policy, while the CI system ensures a dependency change doesn't cause cascading failures in other parts of the repository.

I have no experience with monorepos - but yes, developers have to look over PRs that touch apps. No committing to the main branch!

Also what I have found to be essential to enable technical non-coders (and juniors! and contractors!) is that PR reviewers are responsible for merging and any needed final quality tweaks.

This isn't going to work with every team. Monorepos would make this whole effort harder, I'd guess that just teaching people what to edit would be painful.

Alternatively, you could have some ui that allowed writing to the wiki and it converted it to a commit. Basically the same way that editing the readme can be done at GitHub. In any case, as mentioned in a different comment. Most of the wiki is edited by developers anyway

Git is another level. But I have seen documentation of Linux systems in Google Docs. Commands, fragments of config files etc. This can burn your brain for sure.

Therefore Markdown should have higher priority than some crappy level Word or Excel skills. Even if 80% of endusers will use Markdown wiki/docs just as viewers, there is no point of hogtie sysdmins/developers and ask them to document in Word, google docs and keep data in excel files

The solution to this is to make a UI which can be used like a wiki, but in fact creates a git commit for each edit. Allow documentation-only changes without reviews or pull requests etc.

Still use ACL's in the monorepo so that people can edit their own documentation with a single click, but to edit another teams docs requires some kind of pull request/approval from that team.

Create a culture that code changes must have accompanying documentation changes, and that any substantial code change without documentation changes needs a good reason.

Then everyone can use the tools they are familiar with, and still get all the benefits of history and always-uptodateness.

If you can learn pivot tables in Excel, you can learn markdown.

THIS ^^^

Google took this approach internally using markdown files (If I remember correctly).

Perforce is also going this way - https://www.perforce.com/manuals/swarm/Content/Swarm/basics.... - but I wish more (right now it's only in their "project overview pages.")

This allows for code reviews on the doc too, easier to auto-generate, fix, etc - than non-file interface like wiki.

One gotcha - if your playbook is stored there, make sure it's backup'd on secure external USB drives, as the source system, or the markdown render, or something else needed to accomplish this may go down, and now you and your team/project are going to be affected.

Like pre-rendered to .html, .chm, even why not pdf files - whatever it takes just to be able for your oncall personnel to read them back if need to.

Presumably your on-call personnel will have those repos checked out?

What if your source system goes down, can't connect to your local machine, needs to use VM - no the oncall needs to have the USB stick or more, and use it any other company laptop.

Hackdoc itself has a mode to run from a local checkout, with no other service dependencies (vs. the production mode that expects a git/grpc proxy service to access the live repository), and as it's Go it can easily be moved around as a single, relocatable binary that will run from nearly all operating systems.

> Google took this approach internally using markdown files (If I remember correctly).

Yes: https://www.usenix.org/sites/default/files/conference/protec...

I feel like there's a vast difference between documentation relevant to code and a lot of the stuff accumulating in a company wiki. And if you put the latter in a global path, it doesn't become magically better maintained just because your wiki is backed by a repo.

Age without further context is in any case a terrible indicator of relevance. What's IMHO important is a culture of providing the context with your entries.

I prefer this as well (except for the monorepo part :) ) for anything that concerns the code/app in any way. We chose Slab for our wiki partly because it can surface markdown files from github. So, the onboarding guide just links to relevant markdown files right in Slab.

This looks great and I wish my company adopted the monorepo & bazel. The navigation to //devtools from the link you shared results in a 404 however - perhaps the tool's routing is confused by the bazel "//<project>" syntax? Maybe not as I see the url path looks correct, maybe parent directory links should not show as active if there is nothing to serve in the parent directory.

It's broken :) This is mildly internal for now, and needs a bunch of bug fixes before release.

The behaviour I would expect for this is that the 'devtools' part of the path shouldn't be clickable - as there isn't any documentation markdown in that path of the repository. I'll see if I can implement this today.

EDIT: fixed.