7 ms·

We're in the same boat. I brought Confluence into our org almost a decade ago — it was the best collaborative wiki tool at the time. Over time the price has inc

We're in the same boat. I brought Confluence into our org almost a decade ago — it was the best collaborative wiki tool at the time. Over time the price has increased while the quality of the tool has not kept pace with other options. This seems to be the trend as software companies grow into large "enterprise" providers. Looking at our Confluence usage over the years, I noticed that we use it primarily as a knowledgebase/documentation tool and less for collaboration. With our on-prem license expiring, we are migrating to a dedicated knowledgebase for our FAQ and frequently changing content and switching to a Markdown tool + Git for our more formal documentation.

gwright 3y ago
Could you share what markdown/git tooling you've identified?
- HankB99 3y ago
  Not speaking for the GP. I use MkDocs and keep my personal notes. The only weak spot for me is that I haven't fully grokked search and as my notes grow, it can be harder to find things. I alternate between figuring out how search and how to bolt on some other search utility. MkDocs includes a utility to publish to Github pages but I keep my notes on a self hosted Gitea server and serve using "python -m http".
  - wredue 3y ago
    Is this a fully collaborative tooling with self linking? Having hundreds of out of date, and insecure word documents is a dismal affair when you get a call in the middle of the night. For issue resolution, documents steps are moving right in to the ticketing system for linkage to incidents. That’s fine. For general documentation though. It doesn’t belong in the ticketing system and what a pain in my ass.
    - HankB99 3y ago
      If I understand your question, it's a lot simpler than that. (Simpler as in not that functional.) It represents the directory structure as cascading menus. I edit using VS Code and it provides help with linking from one document to another, including navigating to the file and even linking second level ('##') headings. MkDocs can report broken links when it builds the site. Collaboration could be through sharing a Git repo. Perhaps other other ways I can't think of at this moment. Any way you could collaborate editing text files should work.
  - nvm0n2 3y ago
    Take a look at mkdocs-material, it's not just a theme, it adds some local-side search as well. Still with fully static pages.
    - dnsmichi 3y ago
      The search works great. I'm using MkDocs with Material as my personal handbook because of the simplicity -- for example, I usually remember great articles in conversations but always forget their location. Since I started writing my newsletter https://opsindev.news/ https://opsindev.news/ including an MkDocs web archive, I can share interesting URLs way faster :) Or let folks discover it by themselves, using the search. Configuration in https://gitlab.com/dnsmichi/opsindev.news/-/blob/main/mkdocs.yml?ref_type=heads https://gitlab.com/dnsmichi/opsindev.news/-/blob/main/mkdocs... Material for MkDocs also has an insiders build, accessible through sponsorship. https://squidfunk.github.io/mkdocs-material/insiders/ https://squidfunk.github.io/mkdocs-material/insiders/ These features add more value to MkDocs -- I initially joined to get GDPR-compliant cookie banners and stayed to support a great project.
  - gwright 3y ago
    Has anyone identified an easy/feasible way to add SSO authentication to github pages?
    - spondylosaurus 3y ago
      https://www.twilio.com/blog/keep-internal-docs-secure-okta-netlify https://www.twilio.com/blog/keep-internal-docs-secure-okta-n... This is one, although you'll need to use Netlify instead of GitHub Pages proper.
    - kosikond 3y ago
      OTOH couldn't it be done with Cloudflare Zero Trust ? Have the GH Pages (sub)domain proxied with CF, protect the URL with Zero Trust, for SSO itself there are several IdP available [0]. First 50 users are not billed. [0]https://developers.cloudflare.com/cloudflare-one/identity/idp-integration/ https://developers.cloudflare.com/cloudflare-one/identity/id...
      - TheNewsIsHere 3y ago
        I haven’t tried doing this, although I’ve thought of it to solve a similar problem, which I ultimately solved by not bothering and just letting GitHub render the docs. (Purely internal technical use cases, so not an issue.) I haven’t experimented, but my first attack would be to query the GH Pages service directly and specify the host header. Bypass Cloudflare entirely. GitHub Pages supports SSO with the enterprise cloud plan, of course.
    - kriberg 3y ago
      We use azure ad for authn to our github organization. That also covers github pages generated from those repos.
      - gwright 3y ago
        I assume that means that every person accessing the pages also needs a github account? I don't mind a requirement for a github account for anyone contributing to the repo but I would like authenticated access for viewing the pages that doesn't require a Github account.
  - squidfunk 3y ago
    Author of Material for MkDocs here. We're currently working on re-architecting the entire search engine and rewriting it from scratch. We're currently based on lunr.js, which is unmaintained as of 2020 and has more or less run its course. We've learned a lot what matters in respect to efficient and user friendly documentation search, and can't wait to give the first version into the hands of our users. I'm convinced that the next iteration of search we'll be releasing will solve many of the shortcomings that our current implementation has. Of course, it will work on the client side as it does now, no server needed, but there will be other options as well, e.g. for when your search index is in the megabytes and too big to ship to clients.
    - HankB99 3y ago
      Many thanks for your efforts here. I'll be looking into Material for MkDocs (the next time I can't find something. ;) )
- belthesar 3y ago
  Obsidian is a pretty good solution for this in my experience
  - vorpalhex 3y ago
    Obsidian does not support collaboration. It's a fantastic tool but strictly singleplayer.
    - belthesar 3y ago
      I used it with a team of 10 folks at my previous job. Everyone worked in a common git repo, and with some smart usage of .gitignore, we were all able to collaborate quite effortlessly, even going so far as to push videos, images, etc to the repo with git-lfs to make the documentation rich and available. It can certainly be multiplayer with a modicum of effort.
      - Zetobal 3y ago
        Wouldn't be feasible for most of our users but nice to know...
    - kepano 3y ago
      Obsidian has a feature called "Shared vaults" which teams use to collaborate. You can also use a shared Git repo, or other cloud/network storage (e.g. Dropbox) https://help.obsidian.md/Obsidian+Sync/Share+remote+vaults https://help.obsidian.md/Obsidian+Sync/Share+remote+vaults
- vorpalhex 3y ago
  For something quick and easy consider https://github.com/gollum/gollum#markups https://github.com/gollum/gollum#markups which powers Github Wikis. Note that multi-user auth is NOT supported out of the box however.
- neovive 3y ago
  Sure. We're focusing first on converting everything to plain Markdown and using a Git repo to manage the content. Writers can use whatever Markdown tool they prefer for this. (I'm using Obsidian and others are iA Writer.) I have yet to decide on the docs publishing tool, but I'm testing Astro, Vitepress, and Markdoc for publishing. I'm leaning towards Astro since it's very flexible, easy to add small bits of interactivity via MDX, and has a nice collection of themes. VitePress is also very nice, super fast, and very easy to publish. Since only the developers and tech writers need to collaborate on the docs, we're following a docs-as-code approach — using GitHub issues, comments, and pull requests.
  - teachrdan 3y ago
    Here's some info about Astro for folks like me who didn't know about it before: "Markdown is commonly used to author text-heavy content like blog posts and documentation. Astro includes built-in support for standard Markdown files that can also include frontmatter YAML to define custom metadata such as a title, description, and tags." https://docs.astro.build/en/guides/markdown-content/ https://docs.astro.build/en/guides/markdown-content/
  - paradox460 3y ago
    You should take a look at foam. It's a toolchain for notes and such, similar to obsidian, but open source. It's main interface is a vscode plugin, but has HTML generators and such, as well as just being markdown, so you can use Pandoc or anything else to make HTML out of it
    - snapplebobapple 3y ago
      I wish people would link software they recommend, because it saves me a lot of confusion when they are semi obscure. I believe this is the software you are referring to? (I'm using obsidian but don't like that it's not opensource and don't like logseq, except for their journals feature so I'm actually quite interested in checking out foam) https://foambubble.github.io/foam/ https://foambubble.github.io/foam/
      - 3y ago
unethical_ban 3y ago
>I brought Confluence into our org almost a decade ago — it was the best collaborative wiki tool at the time I respectfully disagree with that assertion! I remember 2012 (okay, 11 years ago). I had just joined a new team at work, and the documentation for the team was a lot of vendor PDFs and some .txt files from the lead stored on a network drive. The company was just implementing Confluence, but it was slow on client and server side with no HA. That is the fault of the server team, not Atlassian, but still the software was ick. I spun up a shadow-IT Dokuwiki server that was much easier to use for a small team with text-based documentation needs. It had a naive "calendar" plugin that allowed the quick creation of pages based on date, which we used for oncall hand-off. Backup was zipping the data folder on the server. It was probably 3 more years until our hand was forced to use the "enterprise standard" for business continuity purposes.

gwright 3y ago

Could you share what markdown/git tooling you've identified?

HankB99 3y ago
Not speaking for the GP. I use MkDocs and keep my personal notes. The only weak spot for me is that I haven't fully grokked search and as my notes grow, it can be harder to find things. I alternate between figuring out how search and how to bolt on some other search utility. MkDocs includes a utility to publish to Github pages but I keep my notes on a self hosted Gitea server and serve using "python -m http".
- wredue 3y ago
  Is this a fully collaborative tooling with self linking? Having hundreds of out of date, and insecure word documents is a dismal affair when you get a call in the middle of the night. For issue resolution, documents steps are moving right in to the ticketing system for linkage to incidents. That’s fine. For general documentation though. It doesn’t belong in the ticketing system and what a pain in my ass.
  - HankB99 3y ago
    If I understand your question, it's a lot simpler than that. (Simpler as in not that functional.) It represents the directory structure as cascading menus. I edit using VS Code and it provides help with linking from one document to another, including navigating to the file and even linking second level ('##') headings. MkDocs can report broken links when it builds the site. Collaboration could be through sharing a Git repo. Perhaps other other ways I can't think of at this moment. Any way you could collaborate editing text files should work.
- nvm0n2 3y ago
  Take a look at mkdocs-material, it's not just a theme, it adds some local-side search as well. Still with fully static pages.
  - dnsmichi 3y ago
    The search works great. I'm using MkDocs with Material as my personal handbook because of the simplicity -- for example, I usually remember great articles in conversations but always forget their location. Since I started writing my newsletter https://opsindev.news/ https://opsindev.news/ including an MkDocs web archive, I can share interesting URLs way faster :) Or let folks discover it by themselves, using the search. Configuration in https://gitlab.com/dnsmichi/opsindev.news/-/blob/main/mkdocs.yml?ref_type=heads https://gitlab.com/dnsmichi/opsindev.news/-/blob/main/mkdocs... Material for MkDocs also has an insiders build, accessible through sponsorship. https://squidfunk.github.io/mkdocs-material/insiders/ https://squidfunk.github.io/mkdocs-material/insiders/ These features add more value to MkDocs -- I initially joined to get GDPR-compliant cookie banners and stayed to support a great project.
- gwright 3y ago
  Has anyone identified an easy/feasible way to add SSO authentication to github pages?
  - spondylosaurus 3y ago
    https://www.twilio.com/blog/keep-internal-docs-secure-okta-netlify https://www.twilio.com/blog/keep-internal-docs-secure-okta-n... This is one, although you'll need to use Netlify instead of GitHub Pages proper.
  - kosikond 3y ago
    OTOH couldn't it be done with Cloudflare Zero Trust ? Have the GH Pages (sub)domain proxied with CF, protect the URL with Zero Trust, for SSO itself there are several IdP available [0]. First 50 users are not billed. [0]https://developers.cloudflare.com/cloudflare-one/identity/idp-integration/ https://developers.cloudflare.com/cloudflare-one/identity/id...
    - TheNewsIsHere 3y ago
      I haven’t tried doing this, although I’ve thought of it to solve a similar problem, which I ultimately solved by not bothering and just letting GitHub render the docs. (Purely internal technical use cases, so not an issue.) I haven’t experimented, but my first attack would be to query the GH Pages service directly and specify the host header. Bypass Cloudflare entirely. GitHub Pages supports SSO with the enterprise cloud plan, of course.
  - kriberg 3y ago
    We use azure ad for authn to our github organization. That also covers github pages generated from those repos.
    - gwright 3y ago
      I assume that means that every person accessing the pages also needs a github account? I don't mind a requirement for a github account for anyone contributing to the repo but I would like authenticated access for viewing the pages that doesn't require a Github account.
- squidfunk 3y ago
  Author of Material for MkDocs here. We're currently working on re-architecting the entire search engine and rewriting it from scratch. We're currently based on lunr.js, which is unmaintained as of 2020 and has more or less run its course. We've learned a lot what matters in respect to efficient and user friendly documentation search, and can't wait to give the first version into the hands of our users. I'm convinced that the next iteration of search we'll be releasing will solve many of the shortcomings that our current implementation has. Of course, it will work on the client side as it does now, no server needed, but there will be other options as well, e.g. for when your search index is in the megabytes and too big to ship to clients.
  - HankB99 3y ago
    Many thanks for your efforts here. I'll be looking into Material for MkDocs (the next time I can't find something. ;) )
belthesar 3y ago
Obsidian is a pretty good solution for this in my experience
- vorpalhex 3y ago
  Obsidian does not support collaboration. It's a fantastic tool but strictly singleplayer.
  - belthesar 3y ago
    I used it with a team of 10 folks at my previous job. Everyone worked in a common git repo, and with some smart usage of .gitignore, we were all able to collaborate quite effortlessly, even going so far as to push videos, images, etc to the repo with git-lfs to make the documentation rich and available. It can certainly be multiplayer with a modicum of effort.
    - Zetobal 3y ago
      Wouldn't be feasible for most of our users but nice to know...
  - kepano 3y ago
    Obsidian has a feature called "Shared vaults" which teams use to collaborate. You can also use a shared Git repo, or other cloud/network storage (e.g. Dropbox) https://help.obsidian.md/Obsidian+Sync/Share+remote+vaults https://help.obsidian.md/Obsidian+Sync/Share+remote+vaults
vorpalhex 3y ago
For something quick and easy consider https://github.com/gollum/gollum#markups https://github.com/gollum/gollum#markups which powers Github Wikis. Note that multi-user auth is NOT supported out of the box however.
neovive 3y ago
Sure. We're focusing first on converting everything to plain Markdown and using a Git repo to manage the content. Writers can use whatever Markdown tool they prefer for this. (I'm using Obsidian and others are iA Writer.) I have yet to decide on the docs publishing tool, but I'm testing Astro, Vitepress, and Markdoc for publishing. I'm leaning towards Astro since it's very flexible, easy to add small bits of interactivity via MDX, and has a nice collection of themes. VitePress is also very nice, super fast, and very easy to publish. Since only the developers and tech writers need to collaborate on the docs, we're following a docs-as-code approach — using GitHub issues, comments, and pull requests.
- teachrdan 3y ago
  Here's some info about Astro for folks like me who didn't know about it before: "Markdown is commonly used to author text-heavy content like blog posts and documentation. Astro includes built-in support for standard Markdown files that can also include frontmatter YAML to define custom metadata such as a title, description, and tags." https://docs.astro.build/en/guides/markdown-content/ https://docs.astro.build/en/guides/markdown-content/
- paradox460 3y ago
  You should take a look at foam. It's a toolchain for notes and such, similar to obsidian, but open source. It's main interface is a vscode plugin, but has HTML generators and such, as well as just being markdown, so you can use Pandoc or anything else to make HTML out of it
  - snapplebobapple 3y ago
    I wish people would link software they recommend, because it saves me a lot of confusion when they are semi obscure. I believe this is the software you are referring to? (I'm using obsidian but don't like that it's not opensource and don't like logseq, except for their journals feature so I'm actually quite interested in checking out foam) https://foambubble.github.io/foam/ https://foambubble.github.io/foam/
    - 3y ago

unethical_ban 3y ago

>I brought Confluence into our org almost a decade ago — it was the best collaborative wiki tool at the time I respectfully disagree with that assertion! I remember 2012 (okay, 11 years ago). I had just joined a new team at work, and the documentation for the team was a lot of vendor PDFs and some .txt files from the lead stored on a network drive. The company was just implementing Confluence, but it was slow on client and server side with no HA. That is the fault of the server team, not Atlassian, but still the software was ick. I spun up a shadow-IT Dokuwiki server that was much easier to use for a small team with text-based documentation needs. It had a naive "calendar" plugin that allowed the quick creation of pages based on date, which we used for oncall hand-off. Backup was zipping the data folder on the server. It was probably 3 more years until our hand was forced to use the "enterprise standard" for business continuity purposes.