We use Notion, and we use it because the product and sales and management folks use it for their work too. It’s fairly cumbersome and infrequently updated, so we just don’t have good documentation overall

We use notion, mostly because someone with influence on the decision already liked it and was using it personally. Not a big fan. Knowledge goes to die in a big sprawl of orphaned pages, documentation goes stale, tables are a meme, bidirectional linking is slow and inaccurate. 3/10 would not recommend

I've worked with notion at various places and have to agree with @UK0810AQ2... I've also worked on a team of Emacs users and we found org-mode better, partly because you can check it into git and use it to generate PDFs and so on if you need to publish it externally.

Most work documentation is either in READMEs in the repo or in Confluence since we're an Atlassian shop. The READMEs don't go stale as fast, so that's a bonus. I hate Confluence with a passion (I don't like wikis in general). Interesting to see the Notion bashing -- it's what Clojure Camp uses and seems OK for that (both reading/navigating and editing). Personally, I use Logseq but it's "local-only" so there's no knowledge sharing or collaboration (you can export pages to HTML and you can sync the source files between machines but it's still intended for one-at-a-time editing). I like the heavily networked notes form -- I thought Notion was meant to be more in that vein...?

Notion has some really cool features, but it's not colocated with the code, so there's an extra step necessary to document things. and it's very easy to write 2/3 of a page on a topic and then walk away, leaving yourself or people in the future to read it and be confused. additionally, because it's like a wiki or linked notes, you have to put in a lot of work to keep it organized: linking pages from other relevant pages, adding tables of contents where necessary, etc.

Yeah, Logseq works well for organizing personal thoughts -- and Clojure Camp is using Notion as, essentially, a CMS for their website(s) and there's no code associated. I think all separate-from-code doc systems suffer from issues (incompleteness, drift, hard to navigate/search).

I want something similar to Unison's system of live docs, maybe Clerk is the way. Imagine a clerk x logseq integration, with everything running on top of a git forge

Previous job used sharepoint and each team had neatly organized dashboards and websites. It was super easy to find documentation. Current job uses Notion and I dislike every single bit of it 😄 For starters, there are no folders like in sharepoint, so every category of “notes” one creates inevitably becomes a gigantic list of documents that are impossible to discover or find. Next, I frequently run into issues where someone claims to have updated a document, but the history section shows no such change ever happening (even though it did). And history only goes back to 30 days (?) unless you pay extra $$$. Also there’s no page versioning, another huge difference from sharepoint. So for important technical documentation, we now just check-in markdown files into a Git repository and create an internal documentation site with it (some teams use mkdoc, others use docusaurus). tl;dr: used sharepoint in the past, loved it. notion is now forced on me, and i dearly miss sharepoint

We’re using a system called Leaflet that we’re building on top of Clerk. Hope to get a first open source release out in the coming weeks.

So... this might come as a joke, but I don't believe in software documentation. I know some people that said that they worked on some place, and they had great docs, and such, but I never had the same experience. What I do believe is on well-written tests, with meaningful names for setup, code extraction, etc; I usually joke about writing your tests in English, explaining what the code does and what it returns, and then putting parenthesis around everything and making it valid Clojure code 😄. Documentation, in my view, works really well if we document the product we're building - not the actual code. What I think is a missed opportunity is to have some tool that reads part of our code, and that we can extract documentation from it - in this way, documents never get stale because if they do, the code is wrong. Another thing I used and liked a lot were some tools like Instana that could monitor my services and they generated a graph of dependencies between services, and also extracted the messages being passed between services.

My company has a dead Notion with various dead wikis before it I’ve found /docs in the git repo to be quite useful as long as it’s low maintenance

> I’ve found /docs in the git repo to be quite useful as long as it’s low maintenance Same. Though I really like organising markdown files with MkDocs. You still can edit/version control/grep the files as you'd do without MkDocs, but MkDocs allows you to generate a nice static website with navigation and the very basic but useful search.

For internally facing knowledge systems: • Atlassian Confluence is very useful and has a rich set of content features and templates, especially useful when coupled with other Atlassian products • Notion is pretty simple to use and rich enough to create effective docs. Lots of templates to support communication within an organisation. I never got into the 'database' side of things, it feels a bit weird to work with, but I think it can be useful if I spend a bit of time For external: • MkDocs is fast and simple to use, coupled with Material for MkDocs I recreated the Practicalli online guides to be much more professional looking Documentation is a highly effective form of communication when practised like any other skill and is valued throughout the organisation you work in. If its not perceived as valuable then its a burden as it wont be maintained (this is one cause of silos that appear in orgs and technical debt when people leave without capturing their experience). I could rant further, but there is little point...

Probably the best documentation I've seen was a GIT repo that combined our technical documentation as well as small command line helper tools. This meant we all had a copy, frequently used it, and could create/update any document. The documents themselves were plain text with markdown where appropriate.

I think it’s good to open source what you can afford to

But potential users of your code will likely have issues/support needs, and it’s wise to consider what sort of support you can afford to commit to

"Open source" is more than just releasing the code, as Daniel says, so think about documentation and support over the long-term. But I would say, as long as you're willing to commit to that, "developing in public" is fine if your company is okay with that -- i.e., the public OSS repo is the system of record for your company's library, rather than just merging in snapshots from time-to-time. That would be my preference. Quite a few companies have a public OSS repo but only merge in code at each release, so that's another option -- but, again, what's in the repo is always "current" with whatever public release they've made.

I think it’s also worth pondering why you want to open source it. IMO, there is a non-neglible cost to making in house code general (and well documented) enough to be useful for public consumption. There is also, even if Rich says it shouldn’t be, the cost of expectations from the users of your OSS work, and as Rich says it should be, the cost of publishing an api which then should be backwards compatible forever. Keeping your stuff in house saves you from all this, but then you loose on the potential employer branding that might come with OSS contributions and also perhaps the employee satisfaction which comes with the same. At Ardoq, we’ve open sourced some stuff, haven’t really seen much traction with that, and we also tend to contribute back to OSS we use in various ways, I personally find the latter having higher ROI than the former.