We are trying to find a good tool for internal technical documentation. E.g. playbooks for site operations, or how-to docs on how to use a particular library. The documentation will contain a lot of code/command snippets.
We currently use Google Docs because of its very good WYSIWYG capabilities, and most importantly, its commenting system that allows us to discuss a particular issue and keep record of that discussion. However, Google docs is not made for code documentation so it's a bit clunky sometimes (e.g. it will capitalize the first letters of sentences etc...).
We briefly tried the GitHub wiki, but it severely lacked on collaboration/commenting and ease of editing.
What tools do people recommend for editing internal documentation?
You should take a look at Notion.so. I'm using it personally to manage my code/snippets, how-tos, and pretty much all of my knowledgebase management. It's become my second brain. With my team, we collaborate on Notion Kanban boards for project management, document collaboration, and since our company uses G-Suites, I'm using an unofficial integration (via Zappier and notion-automations.com) to import our google docs into customized notion databases to improve discovery/access (less searching, more doing) - Notion's databases support multiple views for databases: Table, List, Gallery, Calendar, Kanban, and Timeline views. Documents we collaborate on live on a notion "page" where we can @comment inline or on the overall document using a comments tool a the top of every document. We also have a Slack integration that notifies users in slack channels when there's a comment on a document or database they're following or something is assigned to them. Block creation, text/code/snippet formatting are done using markdown. Notion has integrations with Trello, Miro, Gdocs, MS Excel, Word, and others. They are working on an API to enable more customization and integrations. Most important, you are not locked into their ecosystem. If you ever decide to leave Notion, you can export all of your content in markdown, pdf, and html.
I agree, Notion is super easy to use yet powerful tool. You can write directly in markdown and code snippets have syntax highlighting.
Thanks for your advice (and to Marc as well). I have tried Notion a little bit and was very impressed by its interface, but we never got into it for real. Maybe this is a good reason to give it a try.
Me and a lot of colleagues have done documentation collaboratively with https://hackmd.io/ which also comes as an open source fork as https://hedgedoc.org/. The first has commenting function, the latter hasn't. Both make it easy to do doc sprints synchronously which means everybody is on the phone at the same time and write down documentation. As you do this with Markdown you can use your writing with https://squidfunk.github.io/mkdocs-material/ e.g. which is a static site generator running on Python and build beautiful documentation from Markdown files. If you want to build with https://gohugo.io/ I recommend https://www.docsy.dev/ theme.
We do scholarly writing and documentation with GitLab which we host on-premise. GitHub and GitLab come with sophisticated workflows for commenting and quality assurance if you learn to branch and merge which is for a lot of folks a steep learning curve. To onboard colleagues I recommend starting with HedgeDoc first and then migrate to more advanced workflows with Git(Lab|Hub).
Thanks, that was very thorough. My concern with these kinds of approaches is that they impose barriers (in terms of time and workflow friendliness) to updating and commenting on the docs. The GoogleDocs-style writing and commenting are more frictionless in this sense.