9 ms·

I'm convinced that documentation, even for large companies, should just be an Obsidian vault of markdown files maintained via git which is just rendered on the

by rcarr 4y ago

I'm convinced that documentation, even for large companies, should just be an Obsidian vault of markdown files maintained via git which is just rendered on the web either using a simple static site generator or using Obsidian Publish. When I brought this up at my last company it got dismissed as being 'too technical'. I know git can be tricky but it cannot be that difficult to teach people from non technical departments add, commit and push and then show maybe one person from each department how to solve conflicts. Alternatively, build non technical people a web interface for editing and committing but allow the devs to just use git as standard. Or there's Obsidian's built in sync but I don't know enough about it to know if it scales well in large organisations. What absolutely is definitely not the solution is Confluence. I have not met anyone who has a positive thing to say about it. The only reason it is being so widely used is because it satisfies whoever is in charge of the finances because it comes bundled with Bitbucket and Jira.

waboremo 4y ago
An easier one stop shop alternative is just Notion. Recommend it for the reason of having an internal wiki/documentation. Probably one of the only real use cases for Notion, everything else (like personal note taking or time organization) is horrible on it.
- rcarr 4y ago
  This was actually my next suggestion when Obsidian got shot down. It's definitely a nice half way house between the two. Again it got dismissed albeit this time with no explanation, I assume because the request for feedback and suggestions wasn't actually anything of the sort but basically a pretend exercise on behalf of management to 'show we're listening'.
  - deleted 4y ago
    [deleted]
icelancer 4y ago
That just sounds like rebuilding Notion internally, and this is coming from someone who uses Obsidian locally and Notion company-wide.
- tryauuum 4y ago
  notion lost appeal when I noticed that search doesn't work. E.g. I have a page with wireguard mentioned in text and I cannot find it when searching for wireguard.
  - flippinburgers 4y ago
    yeah notion's search never seems to provide me with what i am actually looking for.
deleted 4y ago
[deleted]
j7ake 4y ago
I find Dropbox to have much less friction (almost zero) compared to git. In the teams with nontechnical people it is often enough to just use Dropbox. Git requires manually committing, which is friction and people often forget to commit changes. The fact you need one person technical enough to resolve conflicts is already a deal breaker.
- jbverschoor 4y ago
  Well, you can actually just script that. Dropbox is fun, until you want previous versions. At the place I worked for 22 years ago, we had an SMB fileshare for designers/front-end devs (html templates + templating lang), which would simply commit everything to CVS at night.
- PartiallyTyped 4y ago
  Setup a service with Dropbox sdk and python to pull the data, commit them, and push (even forced) to git. At least you will have multiple revisions.
tryauuum 4y ago
confluence is ok, though I think I had problems with literal search: https://jira.atlassian.com/browse/CONFCLOUD-69222 https://jira.atlassian.com/browse/CONFCLOUD-69222 What's the benefit of your solution? I mean git has excellent history lookup capabilities, but that's the only benefit I see. Maybe another one is that you can update documents without leaving cli..
- rcarr 4y ago
  For starters, the Confluence editor is absolutely dire. We can all stand here and sing til the cows come home about how it shouldn't be the world we live in, but the reality is that not a lot of people want to or have the time to write documentation so we should be making it as easy and fast as possible to do. As much friction as possible should be removed. It does not get a hell of a lot easier or quicker than writing a Markdown file. Second, because it is plain text, search is blisteringly fast using any number of different tools. Following on from that for a third benefit: portability. You're not tied to any one service. You can use any text editor for editing and you can use a multitude of different solutions for publishing. Version control? Use whatever you what. Another benefit: easy linking of files using [[wikilinks]] and block inclusion. If this is done properly, you can also use the graph view to get an oversight on how your code affects other parts of the codebase at a glance.
deleted 4y ago
[deleted]
PragmaticPulp 4y ago
> I know git can be tricky but it cannot be that difficult to teach people from non technical departments This is far more difficult than you're suggesting. Git still confuses a lot of junior and mid level devs the second anything deviates from their memorized command workflow. If you're expecting non-technical people to have to learn git just to edit the documentation, they're just not going to use it at all. Writing and aggregating good documentation needs to be easy and simple. Gating documentation behind git is the opposite of that for non technical people.
- rcarr 4y ago
  I do get what you're saying because I struggled with it for ages. There are good GUI tools like Sublime Merge for easy conflict resolution now which would be one solution. I do think a web interface that just automatically commits by just adding your text in addition to the new text along with a warning would probably be the easiest solution and then just have someone edit it after the fact. It's not been my experience that there's a hell of a lot of merge conflicts going on with documentation anyway but I could see how it could happen if you had multiple non technical people actively working on a project. Another not great but possible solution could be for non technical people to work on something like a Google Doc when stuff is in highly active development and to then copy this to a markdown document later when its solidified. I do think that as a society we have to start looking at stuff like this as a new essential skill though. We wouldn't expect people to be working without basic literacy, numeracy and computer skills and I think we are going to have to start looking at upgrading our sense of what basic computer skills entails to include stuff like git and teaching it in schools from an early age.
  - jonwest 4y ago
    GitHub does offer the ability to modify files within the web UI and open a PR from there.
  - remus 4y ago
    I think even the idea of merging changes is a step too far for all but the most technical users. Most user's idea of what it should look like start and end at a word-like UI, so having to introduce the idea of merging different copies together and resolving conflicts is too far outside that view. In my opinion this is why Google docs has become popular because it solves that tricky problem of having to think about how your edits interact with someone else's.
koonsolo 4y ago
That is indeed too technical. Try to explain how inserting an image is not just copy paste.
- rcarr 4y ago
  1. Paste image into assets folder. 2. Write ![imagename](imagename.jpg). It's not that hard really is it.
  - vasco 4y ago
    Have you worked with non-technical teams, ever? Perhaps in teams of very young and gamer-type people this would work, but in any real world team I've been in, this would not in fact be easy unless there's a real time preview and a button you can click that auto-generates that snippet. People would forget the exclamation mark, mixup the brackets with the parenthesis, not know how to reference the right path to the image, and ask a developer to help them out.
    - someguydave 4y ago
      If someone is confused by markdown syntax it is hard to imagine how they contribute professionally.
      - mym1990 4y ago
        Maybe you should try to imagine a little harder. "If You Judge a Fish by Its Ability to Climb a Tree, It Will Live Its Whole Life Believing that It is Stupid"...or in this case you will live your whole life believing every non-technical person around you is stupid...which just sounds miserable for everyone involved.
    - rcarr 4y ago
      Well presumably this would be less of an issue if you had easy to use, easy to search and easy to maintain documentation, you know, maybe in the form of markdown files with a search bar where you could type 'how to paste image into documentation' in case you forgot... At the end of the day, if you've got someone who can't work out how to drag a file into a folder and then type ![imagename](imagename.jpg) after you've shown them a couple of times, is this really the person you want writing the documentation for your process?
Terretta 4y ago
> I'm convinced that documentation, even for large companies, should just be an Obsidian vault of markdown files maintained via git which is just rendered on the web either using a simple static site generator or using Obsidian Publish This, except for normals, sort of exists: Craft: https://www.craft.do/solutions/businesses https://www.craft.do/solutions/businesses Default is internal only, but you can allow sharing, which creates a web URL that can be privately or publicly shared (and can be on your own custom domain). It has versioning, it has comments, it has real time multi-editor collaboration. An entire conference room, in person and virtual, can co-edit in true real time without anything blowing up, a feat not to be tried in Word, or even Google Docs. Most firms should stop looking and just try Craft. Encourage everyone to do everything there, see what happens. Note bene: it happily imports markdown, also exports Word, PDF, Markdown, and Textbundle, and can feed a static site gen. They also keep busy: https://www.craft.do/whats-new https://www.craft.do/whats-new // I use Obsidian for myself, but Craft to collaborate with non-engineers. I've also been known to recommend FOAM to engineering teams, coupled with mkdocs and a good theme for static site gen, such as material for mkdocs: https://foambubble.github.io/foam/ https://foambubble.github.io/foam/ https://github.com/squidfunk/mkdocs-material https://github.com/squidfunk/mkdocs-material For eng teams already living in VS Code, it's hard to beat PKM where you already are.
- primax 4y ago
  This looks great, but no Android or mobile support outside iOS is a big negative
mayas_ 4y ago
I'm a CTO in a startup and all our docs are in .md files, mermaid diagrams with dynamic Table of Content generation. We have two repos: Product (to anything relating to product) and Wiki (anything else, ranging from onboarding checklists, brief design documentation of key parts of the code ... to meta documentation) Although our team is small by many standards (8) everyone likes it. We spend a ridiculously small amount of time on meetings. The obvious and great upside is the code/documentation integration which has virtually 0 context loss. One downside however is indeed the difficulty of git branching to non-developers. Once in while I find myself debugging a messed up version. But I'm willing to pay that price.
- Reitet00 4y ago
  Thanks for sharing! Do you mind describing more technical details about the rendering pipeline for docs that you use?
vsareto 4y ago
>I know git can be tricky but it cannot be that difficult to teach people from non technical departments add, commit and push and then show maybe one person from each department how to solve conflicts Nah, that's going to be a crapshoot. You want a few people who know git and do this for a full time job and that's all they do - manage the documentation git repo.
tomxor 4y ago
> I'm convinced that documentation, even for large companies, should just be an Obsidian vault of markdown files maintained via git I had the same concern, internal documentation should be in a portable format... and I managed to mostly successfully get us to change to MD text files in a git repo. I, and others, were tired of it being locked up in proprietary platforms like google docs - which ironically has terrible search capability and is horribly slow. Some of the devs already wrote documentation in markdown and plain text along side code (Also I hear talking about yourself in the 3rd person is the first sign of madness). So a git backed wiki in text files was what I wanted. But it also needed to generate commits from the front end for the less technical, and preferably needed oauth to delegate access control to some other system. "Golumn" filled this space first I believe, but doesn't (or didn't at the time) have the commit or oauth capability. So I settled on a fork "Jingo" which does. I'm not completely wedded to Jingo, which is a nodejs app, I haven't dug too deeply into it and so my confidence in it is unknown... but this is effectively data driven design, md text files in git... the code (which is not part of the same repo) is disposable. I set this up 3 years ago and haven't touched it at all. This has been mostly successful gaining more traction over time. People who have no clue how to use git are generating gits commits on a daily basis through the front end - others are using the repo directly. Google docs still has it's place for arbitrary word type stuff, but most internal internal reference type material now gets put into the wiki as a preference, since it's way more searchable, and orders of magnitude faster to access. [edit] To be clear, i'm in a small company where it's easier to change or try things like this. I also got the same expected pushback, concern over MD being too limited compared to google docs and the solution being too technical. but if you can just convince people to trial it for long enough with an exit plan, they will usually obtain a more balanced view weighing the tangible benefits more highly and weighing the negatives or concerns less after actually experiencing it... in this case most people realise that all the bells and whistles of google docs are not critical, and the benefits of the searchability, speed and portability are huge.
- rcarr 4y ago
  Hadn't heard of this before, looks very cool. For anyone interested: https://github.com/claudioc/jingo https://github.com/claudioc/jingo
antupis 4y ago
This might be stupid question but why nobody has not built this kind git-based system to nontechnical people.
- Terretta 4y ago
  https://www.craft.do https://www.craft.do
- lastofus 4y ago
  Some people have built it. For example: https://www.macupdate.com/app/mac/49459/draft-control https://www.macupdate.com/app/mac/49459/draft-control
- pxc 4y ago
  There's Gollum, which powers the built-in wikis on GitLab and GitHub. Its web UI handles making commits for you.
ravenstine 4y ago
I wouldn't even bother with the static site generator. While I like the idea of STGs, in my opinion, they all suck. And now there has to be someone to maintain how those pages are rendered and know how whatever thing like Jekyll works. Just let developers either read the markdown files as-is or set their IDE to render markdown previews by default. I prefer the latter because I don't have to wait for someone who's on vacation half the time to render the latest docs. When it comes to API documentation, everything should just be inline comments in the doc format of choice for the team. Don't bother rendering this out, because every flipping tool ever invented for converting inline documentation into HTML fails on something simple. Developers can read the inline docs as-is and/or rely on their IDE to provide them hints from those docs. If you have to deploy your documentation, that's how you know you might as well give up. It's one thing to deploy documentation for 3rd parties, but for documentation being used internally there's few good reasons to turn the documentation into its own website. That's extra work that I've never seen increase productivity or developer happiness. Don't put documentation behind one or two guys with special permissions to press a deploy button. If you do, the documentation will always be out of date as soon as it's rendered. Remove as many reasons that devs won't write documentation as you possibly can.
- rcarr 4y ago
  I do think just using the folder of markdown folders is far preferable to browsing on the web wherever possible but there's definite use cases where it's unavoidable. I do think this is a very strong case for using Obsidian however, because you literally don't have to mess about with maintaining any kind of SSG, you just put `publish: true` in the metadata of whatever note you want publishing and then just click the Publish button and it's there on the website.
- vlmutolo 4y ago
  Rust's rustdoc tool does an excellent job converting comments to HTML. The documentation for almost every public Rust library is automatically rendered and hosted on docs.rs and it's incredible to have that consistency. Just check out this Regex type and the awesome documentation for every method, all taken from inline comments: https://docs.rs/regex/latest/regex/struct.Regex.html https://docs.rs/regex/latest/regex/struct.Regex.html
loudmax 4y ago
This is what the Gitlab wiki does. There's a markdown+git interface for technical folks and a web interface for normal people.
- mgbmtl 4y ago
  It's what we use, and what I find the be the less annoying solution, but there are two big show-stoppers to make it more user-friendly: - the default index on the sidebar doesn't handle sub-directories well (https://gitlab.com/gitlab-org/gitlab/-/issues/17673 https://gitlab.com/gitlab-org/gitlab/-/issues/17673) - we use a pipeline to refresh an index page, but it's duct-tape and annoying to setup. - can't edit only a section of a page, so if the page has a few sections, I often lose track of what exactly I wanted to change (maybe the WYSIWYG helps here, have to admit I have not used it much) Otherwise I like that each project has its wiki, and so instead of one huge messy wiki, it's a few smaller messy wiki, easier to cleanup and have clear owners.
csharpminor 4y ago
I don't like Confluence either, but the platform is only 10% of the problem. Knowledge Management platforms are something that PMs love to debate, purchase, and use to get promotions. So you end up with a company that has 6+ platforms. This is way worse than having one unified, crappy-UX, wiki. Finding the perfect documentation platform becomes a waiting-for-superman game. Everyone loves to complain, but nobody wants to put in the actual work to write clear content, define information structure, consider audience, etc. The real solution is hiring people who are excellent writers. To do this, leadership must be good at reading and writing themselves (not a given) and be able to recognize top contributors.
grok22 4y ago
You talking about 'wiki'?
kccqzy 4y ago
You cannot expect non-technical people to use git from the command line. I still like your idea though: the documentation can be based on markdown files in a git repository, but then you have to build or find a web-based WYSIWYG editor with Git support for non-technical folks. If you use GitHub already, it wouldn't actually be so bad to teach the non-technical folks to use the Git UI only to make documentation changes.
rco8786 4y ago
Saddling entire companies with having to learn git, even at a basic level, is a hilarious idea.
kfrzcode 4y ago
I like Confluence! It serves it purposes and provides a lot of niceties, and is - as you mention - integrated with other Atlassian tooling. Nice ecosystem!
- kfrzcode 4y ago
  * its
howenterprisey 4y ago
I use Confluence pretty heavily at work (I write most of our docs) and I like it. Any annoying UI elements, I hide with ublock origin. I don't mind the lag, although I do wish it were faster.
amendegree 4y ago
You'd have a much easier time getting this adopted if you created a fancy GUI on top of the infra you just detailed out. Most people don't want to deal with git, no one wants to write in markdown all day, and the more obstacles you introduce to making documentation the less documentation gets made. If the two options are confluence and sharepoint I choose confluence every time. Somehow people have decided that because sharepoint can do document store and html it's a kb. and because it comes with O365 exec's love it because its "free".
throwawaaarrgh 4y ago
Does using Git contribute anything of value to the documentation that you could not possibly get without git? The answer is, of course: no. You just want it because it's familiar to you. Which is fine... if you were the only person using it. Confluence is actually the best solution, hands down. It has a WYSIWYG. It supports Markdown. It has an API. It versions all content. It has fine-grained access control. It does not require granting a user access to a repo to write to a file. It has much more rich content to better convey information clearly to humans. It has full text search. Page management is simple (rename a page and it auto-redirects). And no other solution does all of this as easily or effectively. The people who complain about Confluence simply don't care about use cases outside their own, and haven't taken the time to learn it. I am 100x more productive with Confluence than you are with Git and Markdown. And real people will actually be able to use what I've made there without learning complex tools or jumping through hoops.
- rcarr 4y ago
- therealdrag0 4y ago
  I agree except I’ve been using Quip recently and it’s been a nice alternative to Confluence albeit similar.
mehh 4y ago
Ha yeah good luck with that, many people think confluence is too technical to use!
warrentr 4y ago
This approach is definitely possible with a good web-based git IDE. We use gitlab's webIDE and have taught a few very non-technical (even temporary) employees how to do simple commits of markdown files (the trick here is high visibility into their commits -slack messages- and safeguards to make sure important things don't go live via CI too soon). There's a number of rough edges to sort out but this is vastly simpler, faster, more flexible etc for many situations (and amazing to not be using jira or wordpress :) )
- splittingTimes 4y ago
  I always marvel at gitlabs handbook and would love to introduce it to our company. Are there any tutorials how to set it up? (I don't mean how to set up gitlab, but rather which tools you need and how to set up the render pipeline, server etc to enable a markdown wiki/handbook?
  - peterbozso 4y ago
    GitLab employee here. This page of our handbook can be a good starting point to build your own: https://about.gitlab.com/company/culture/all-remote/handbook-first-documentation/#tools-for-building-a-handbook https://about.gitlab.com/company/culture/all-remote/handbook...
tqi 4y ago
I don't think documentation is a problem with a technical solution - it's an organizational commitment and incentives problem.
baby 4y ago
I couldn't disagree more, every ounce of friction that you add to the process of writing documentation is dozens if not hundreds of documents that could have been written and are not going to be. Unless of course there's a good reason for maintaining your docs in markdown files, but all of them?
zppln 4y ago
This sounds like a programmer's rather naive take to be honest. Available PLM/PDMs could be improved a lot yes, but you're not gonna replace them by slapping a GUI on git (I mean, you could do that but it's really just a pretty small part of the problem space).
foobarbecue 4y ago
I'll say a positive thing about Confluence from the point of view of a mars rover operator. We use it as our main reference on shift and it works great for us. We migrated from twiki and the fact that the search works, everybody can edit easily, and it has a bunch of useful integrations including draw.io . I do wish it had markup or html editing.
johnwalkr 4y ago
Git is not that complicated and this may work for purely internal software docs. But good luck scaling your org, working with customers, investors, vendors etc and not ending up with at least done MS office documents and email as the only record of what is the latest version.

by rcarr 4y ago

waboremo 4y ago

An easier one stop shop alternative is just Notion. Recommend it for the reason of having an internal wiki/documentation. Probably one of the only real use cases for Notion, everything else (like personal note taking or time organization) is horrible on it.

rcarr 4y ago
This was actually my next suggestion when Obsidian got shot down. It's definitely a nice half way house between the two. Again it got dismissed albeit this time with no explanation, I assume because the request for feedback and suggestions wasn't actually anything of the sort but basically a pretend exercise on behalf of management to 'show we're listening'.
- deleted 4y ago
  [deleted]

icelancer 4y ago

That just sounds like rebuilding Notion internally, and this is coming from someone who uses Obsidian locally and Notion company-wide.

tryauuum 4y ago
notion lost appeal when I noticed that search doesn't work. E.g. I have a page with wireguard mentioned in text and I cannot find it when searching for wireguard.
- flippinburgers 4y ago
  yeah notion's search never seems to provide me with what i am actually looking for.

deleted 4y ago

[deleted]

j7ake 4y ago

I find Dropbox to have much less friction (almost zero) compared to git. In the teams with nontechnical people it is often enough to just use Dropbox. Git requires manually committing, which is friction and people often forget to commit changes. The fact you need one person technical enough to resolve conflicts is already a deal breaker.

jbverschoor 4y ago
Well, you can actually just script that. Dropbox is fun, until you want previous versions. At the place I worked for 22 years ago, we had an SMB fileshare for designers/front-end devs (html templates + templating lang), which would simply commit everything to CVS at night.
PartiallyTyped 4y ago
Setup a service with Dropbox sdk and python to pull the data, commit them, and push (even forced) to git. At least you will have multiple revisions.

tryauuum 4y ago

confluence is ok, though I think I had problems with literal search: https://jira.atlassian.com/browse/CONFCLOUD-69222 https://jira.atlassian.com/browse/CONFCLOUD-69222 What's the benefit of your solution? I mean git has excellent history lookup capabilities, but that's the only benefit I see. Maybe another one is that you can update documents without leaving cli..

rcarr 4y ago
For starters, the Confluence editor is absolutely dire. We can all stand here and sing til the cows come home about how it shouldn't be the world we live in, but the reality is that not a lot of people want to or have the time to write documentation so we should be making it as easy and fast as possible to do. As much friction as possible should be removed. It does not get a hell of a lot easier or quicker than writing a Markdown file. Second, because it is plain text, search is blisteringly fast using any number of different tools. Following on from that for a third benefit: portability. You're not tied to any one service. You can use any text editor for editing and you can use a multitude of different solutions for publishing. Version control? Use whatever you what. Another benefit: easy linking of files using [[wikilinks]] and block inclusion. If this is done properly, you can also use the graph view to get an oversight on how your code affects other parts of the codebase at a glance.

deleted 4y ago

[deleted]

PragmaticPulp 4y ago

> I know git can be tricky but it cannot be that difficult to teach people from non technical departments This is far more difficult than you're suggesting. Git still confuses a lot of junior and mid level devs the second anything deviates from their memorized command workflow. If you're expecting non-technical people to have to learn git just to edit the documentation, they're just not going to use it at all. Writing and aggregating good documentation needs to be easy and simple. Gating documentation behind git is the opposite of that for non technical people.

rcarr 4y ago
I do get what you're saying because I struggled with it for ages. There are good GUI tools like Sublime Merge for easy conflict resolution now which would be one solution. I do think a web interface that just automatically commits by just adding your text in addition to the new text along with a warning would probably be the easiest solution and then just have someone edit it after the fact. It's not been my experience that there's a hell of a lot of merge conflicts going on with documentation anyway but I could see how it could happen if you had multiple non technical people actively working on a project. Another not great but possible solution could be for non technical people to work on something like a Google Doc when stuff is in highly active development and to then copy this to a markdown document later when its solidified. I do think that as a society we have to start looking at stuff like this as a new essential skill though. We wouldn't expect people to be working without basic literacy, numeracy and computer skills and I think we are going to have to start looking at upgrading our sense of what basic computer skills entails to include stuff like git and teaching it in schools from an early age.
- jonwest 4y ago
  GitHub does offer the ability to modify files within the web UI and open a PR from there.
- remus 4y ago
  I think even the idea of merging changes is a step too far for all but the most technical users. Most user's idea of what it should look like start and end at a word-like UI, so having to introduce the idea of merging different copies together and resolving conflicts is too far outside that view. In my opinion this is why Google docs has become popular because it solves that tricky problem of having to think about how your edits interact with someone else's.

koonsolo 4y ago

That is indeed too technical. Try to explain how inserting an image is not just copy paste.

rcarr 4y ago
1. Paste image into assets folder. 2. Write ![imagename](imagename.jpg). It's not that hard really is it.
- vasco 4y ago
  Have you worked with non-technical teams, ever? Perhaps in teams of very young and gamer-type people this would work, but in any real world team I've been in, this would not in fact be easy unless there's a real time preview and a button you can click that auto-generates that snippet. People would forget the exclamation mark, mixup the brackets with the parenthesis, not know how to reference the right path to the image, and ask a developer to help them out.
  - someguydave 4y ago
    If someone is confused by markdown syntax it is hard to imagine how they contribute professionally.
    - mym1990 4y ago
      Maybe you should try to imagine a little harder. "If You Judge a Fish by Its Ability to Climb a Tree, It Will Live Its Whole Life Believing that It is Stupid"...or in this case you will live your whole life believing every non-technical person around you is stupid...which just sounds miserable for everyone involved.
  - rcarr 4y ago
    Well presumably this would be less of an issue if you had easy to use, easy to search and easy to maintain documentation, you know, maybe in the form of markdown files with a search bar where you could type 'how to paste image into documentation' in case you forgot... At the end of the day, if you've got someone who can't work out how to drag a file into a folder and then type ![imagename](imagename.jpg) after you've shown them a couple of times, is this really the person you want writing the documentation for your process?

Terretta 4y ago

> I'm convinced that documentation, even for large companies, should just be an Obsidian vault of markdown files maintained via git which is just rendered on the web either using a simple static site generator or using Obsidian Publish This, except for normals, sort of exists: Craft: https://www.craft.do/solutions/businesses https://www.craft.do/solutions/businesses Default is internal only, but you can allow sharing, which creates a web URL that can be privately or publicly shared (and can be on your own custom domain). It has versioning, it has comments, it has real time multi-editor collaboration. An entire conference room, in person and virtual, can co-edit in true real time without anything blowing up, a feat not to be tried in Word, or even Google Docs. Most firms should stop looking and just try Craft. Encourage everyone to do everything there, see what happens. Note bene: it happily imports markdown, also exports Word, PDF, Markdown, and Textbundle, and can feed a static site gen. They also keep busy: https://www.craft.do/whats-new https://www.craft.do/whats-new // I use Obsidian for myself, but Craft to collaborate with non-engineers. I've also been known to recommend FOAM to engineering teams, coupled with mkdocs and a good theme for static site gen, such as material for mkdocs: https://foambubble.github.io/foam/ https://foambubble.github.io/foam/ https://github.com/squidfunk/mkdocs-material https://github.com/squidfunk/mkdocs-material For eng teams already living in VS Code, it's hard to beat PKM where you already are.

primax 4y ago
This looks great, but no Android or mobile support outside iOS is a big negative

mayas_ 4y ago

I'm a CTO in a startup and all our docs are in .md files, mermaid diagrams with dynamic Table of Content generation. We have two repos: Product (to anything relating to product) and Wiki (anything else, ranging from onboarding checklists, brief design documentation of key parts of the code ... to meta documentation) Although our team is small by many standards (8) everyone likes it. We spend a ridiculously small amount of time on meetings. The obvious and great upside is the code/documentation integration which has virtually 0 context loss. One downside however is indeed the difficulty of git branching to non-developers. Once in while I find myself debugging a messed up version. But I'm willing to pay that price.

Reitet00 4y ago
Thanks for sharing! Do you mind describing more technical details about the rendering pipeline for docs that you use?

vsareto 4y ago

>I know git can be tricky but it cannot be that difficult to teach people from non technical departments add, commit and push and then show maybe one person from each department how to solve conflicts Nah, that's going to be a crapshoot. You want a few people who know git and do this for a full time job and that's all they do - manage the documentation git repo.

tomxor 4y ago

> I'm convinced that documentation, even for large companies, should just be an Obsidian vault of markdown files maintained via git I had the same concern, internal documentation should be in a portable format... and I managed to mostly successfully get us to change to MD text files in a git repo. I, and others, were tired of it being locked up in proprietary platforms like google docs - which ironically has terrible search capability and is horribly slow. Some of the devs already wrote documentation in markdown and plain text along side code (Also I hear talking about yourself in the 3rd person is the first sign of madness). So a git backed wiki in text files was what I wanted. But it also needed to generate commits from the front end for the less technical, and preferably needed oauth to delegate access control to some other system. "Golumn" filled this space first I believe, but doesn't (or didn't at the time) have the commit or oauth capability. So I settled on a fork "Jingo" which does. I'm not completely wedded to Jingo, which is a nodejs app, I haven't dug too deeply into it and so my confidence in it is unknown... but this is effectively data driven design, md text files in git... the code (which is not part of the same repo) is disposable. I set this up 3 years ago and haven't touched it at all. This has been mostly successful gaining more traction over time. People who have no clue how to use git are generating gits commits on a daily basis through the front end - others are using the repo directly. Google docs still has it's place for arbitrary word type stuff, but most internal internal reference type material now gets put into the wiki as a preference, since it's way more searchable, and orders of magnitude faster to access. [edit] To be clear, i'm in a small company where it's easier to change or try things like this. I also got the same expected pushback, concern over MD being too limited compared to google docs and the solution being too technical. but if you can just convince people to trial it for long enough with an exit plan, they will usually obtain a more balanced view weighing the tangible benefits more highly and weighing the negatives or concerns less after actually experiencing it... in this case most people realise that all the bells and whistles of google docs are not critical, and the benefits of the searchability, speed and portability are huge.

rcarr 4y ago
Hadn't heard of this before, looks very cool. For anyone interested: https://github.com/claudioc/jingo https://github.com/claudioc/jingo

antupis 4y ago

This might be stupid question but why nobody has not built this kind git-based system to nontechnical people.

Terretta 4y ago
https://www.craft.do https://www.craft.do
lastofus 4y ago
Some people have built it. For example: https://www.macupdate.com/app/mac/49459/draft-control https://www.macupdate.com/app/mac/49459/draft-control
pxc 4y ago
There's Gollum, which powers the built-in wikis on GitLab and GitHub. Its web UI handles making commits for you.

ravenstine 4y ago

I wouldn't even bother with the static site generator. While I like the idea of STGs, in my opinion, they all suck. And now there has to be someone to maintain how those pages are rendered and know how whatever thing like Jekyll works. Just let developers either read the markdown files as-is or set their IDE to render markdown previews by default. I prefer the latter because I don't have to wait for someone who's on vacation half the time to render the latest docs. When it comes to API documentation, everything should just be inline comments in the doc format of choice for the team. Don't bother rendering this out, because every flipping tool ever invented for converting inline documentation into HTML fails on something simple. Developers can read the inline docs as-is and/or rely on their IDE to provide them hints from those docs. If you have to deploy your documentation, that's how you know you might as well give up. It's one thing to deploy documentation for 3rd parties, but for documentation being used internally there's few good reasons to turn the documentation into its own website. That's extra work that I've never seen increase productivity or developer happiness. Don't put documentation behind one or two guys with special permissions to press a deploy button. If you do, the documentation will always be out of date as soon as it's rendered. Remove as many reasons that devs won't write documentation as you possibly can.

rcarr 4y ago
I do think just using the folder of markdown folders is far preferable to browsing on the web wherever possible but there's definite use cases where it's unavoidable. I do think this is a very strong case for using Obsidian however, because you literally don't have to mess about with maintaining any kind of SSG, you just put `publish: true` in the metadata of whatever note you want publishing and then just click the Publish button and it's there on the website.
vlmutolo 4y ago
Rust's rustdoc tool does an excellent job converting comments to HTML. The documentation for almost every public Rust library is automatically rendered and hosted on docs.rs and it's incredible to have that consistency. Just check out this Regex type and the awesome documentation for every method, all taken from inline comments: https://docs.rs/regex/latest/regex/struct.Regex.html https://docs.rs/regex/latest/regex/struct.Regex.html

loudmax 4y ago

This is what the Gitlab wiki does. There's a markdown+git interface for technical folks and a web interface for normal people.

mgbmtl 4y ago
It's what we use, and what I find the be the less annoying solution, but there are two big show-stoppers to make it more user-friendly: - the default index on the sidebar doesn't handle sub-directories well (https://gitlab.com/gitlab-org/gitlab/-/issues/17673 https://gitlab.com/gitlab-org/gitlab/-/issues/17673) - we use a pipeline to refresh an index page, but it's duct-tape and annoying to setup. - can't edit only a section of a page, so if the page has a few sections, I often lose track of what exactly I wanted to change (maybe the WYSIWYG helps here, have to admit I have not used it much) Otherwise I like that each project has its wiki, and so instead of one huge messy wiki, it's a few smaller messy wiki, easier to cleanup and have clear owners.

csharpminor 4y ago

I don't like Confluence either, but the platform is only 10% of the problem. Knowledge Management platforms are something that PMs love to debate, purchase, and use to get promotions. So you end up with a company that has 6+ platforms. This is way worse than having one unified, crappy-UX, wiki. Finding the perfect documentation platform becomes a waiting-for-superman game. Everyone loves to complain, but nobody wants to put in the actual work to write clear content, define information structure, consider audience, etc. The real solution is hiring people who are excellent writers. To do this, leadership must be good at reading and writing themselves (not a given) and be able to recognize top contributors.

grok22 4y ago

You talking about 'wiki'?

kccqzy 4y ago

You cannot expect non-technical people to use git from the command line. I still like your idea though: the documentation can be based on markdown files in a git repository, but then you have to build or find a web-based WYSIWYG editor with Git support for non-technical folks. If you use GitHub already, it wouldn't actually be so bad to teach the non-technical folks to use the Git UI only to make documentation changes.

rco8786 4y ago

Saddling entire companies with having to learn git, even at a basic level, is a hilarious idea.

kfrzcode 4y ago

I like Confluence! It serves it purposes and provides a lot of niceties, and is - as you mention - integrated with other Atlassian tooling. Nice ecosystem!

kfrzcode 4y ago
* its

howenterprisey 4y ago

I use Confluence pretty heavily at work (I write most of our docs) and I like it. Any annoying UI elements, I hide with ublock origin. I don't mind the lag, although I do wish it were faster.

amendegree 4y ago

You'd have a much easier time getting this adopted if you created a fancy GUI on top of the infra you just detailed out. Most people don't want to deal with git, no one wants to write in markdown all day, and the more obstacles you introduce to making documentation the less documentation gets made. If the two options are confluence and sharepoint I choose confluence every time. Somehow people have decided that because sharepoint can do document store and html it's a kb. and because it comes with O365 exec's love it because its "free".

throwawaaarrgh 4y ago

Does using Git contribute anything of value to the documentation that you could not possibly get without git? The answer is, of course: no. You just want it because it's familiar to you. Which is fine... if you were the only person using it. Confluence is actually the best solution, hands down. It has a WYSIWYG. It supports Markdown. It has an API. It versions all content. It has fine-grained access control. It does not require granting a user access to a repo to write to a file. It has much more rich content to better convey information clearly to humans. It has full text search. Page management is simple (rename a page and it auto-redirects). And no other solution does all of this as easily or effectively. The people who complain about Confluence simply don't care about use cases outside their own, and haven't taken the time to learn it. I am 100x more productive with Confluence than you are with Git and Markdown. And real people will actually be able to use what I've made there without learning complex tools or jumping through hoops.

rcarr 4y ago
therealdrag0 4y ago
I agree except I’ve been using Quip recently and it’s been a nice alternative to Confluence albeit similar.

mehh 4y ago

Ha yeah good luck with that, many people think confluence is too technical to use!

warrentr 4y ago

This approach is definitely possible with a good web-based git IDE. We use gitlab's webIDE and have taught a few very non-technical (even temporary) employees how to do simple commits of markdown files (the trick here is high visibility into their commits -slack messages- and safeguards to make sure important things don't go live via CI too soon). There's a number of rough edges to sort out but this is vastly simpler, faster, more flexible etc for many situations (and amazing to not be using jira or wordpress :) )

splittingTimes 4y ago
I always marvel at gitlabs handbook and would love to introduce it to our company. Are there any tutorials how to set it up? (I don't mean how to set up gitlab, but rather which tools you need and how to set up the render pipeline, server etc to enable a markdown wiki/handbook?
- peterbozso 4y ago
  GitLab employee here. This page of our handbook can be a good starting point to build your own: https://about.gitlab.com/company/culture/all-remote/handbook-first-documentation/#tools-for-building-a-handbook https://about.gitlab.com/company/culture/all-remote/handbook...

tqi 4y ago

I don't think documentation is a problem with a technical solution - it's an organizational commitment and incentives problem.

baby 4y ago

I couldn't disagree more, every ounce of friction that you add to the process of writing documentation is dozens if not hundreds of documents that could have been written and are not going to be. Unless of course there's a good reason for maintaining your docs in markdown files, but all of them?

zppln 4y ago

This sounds like a programmer's rather naive take to be honest. Available PLM/PDMs could be improved a lot yes, but you're not gonna replace them by slapping a GUI on git (I mean, you could do that but it's really just a pretty small part of the problem space).

foobarbecue 4y ago

I'll say a positive thing about Confluence from the point of view of a mars rover operator. We use it as our main reference on shift and it works great for us. We migrated from twiki and the fact that the search works, everybody can edit easily, and it has a bunch of useful integrations including draw.io . I do wish it had markup or html editing.

johnwalkr 4y ago

Git is not that complicated and this may work for purely internal software docs. But good luck scaling your org, working with customers, investors, vendors etc and not ending up with at least done MS office documents and email as the only record of what is the latest version.