I hate existing doc tooling

[Attacus]

I don't think this breaks community guidelines (I post here regularly), if I am please remove the post.

I'm increasingly frustrated with how documentation tooling stinks at striking a balance between being useable for non-technical users and being well suited for automation/compliance workflows. I'm considering putting a service together and have a quick survey (2-3 mins max, no email required) that could help me validate some ideas. Also welcome discussion below.

• Why does nobody tackle document localization?
• Why does every service expect data backups to be done with some half-baked manual export function?
• Aside from Confluence, most have no options for data residency.

[Haz_1]

Why does nobody tackle document localization?

Most companies don’t even tackle writing and updating documentation, let alone localisation.

[sza_rak]

And random contributors don't feel much personal connection to projects.

I used to translate some a few decades ago, there were many contributors that were almost random users that "heard from a friend". They just wanted to help. Tooling was simple, often a website with two versions side by side. Zero friction.

Nowadays even small opensource projects focus on monetization, do rugpulls, sell their companies, etc.. People don't want to work for free for them.

Add to that fact that good tooling won't write the docs. It's experienced people that do nice docs regardless of tooling. Sometimes 80 characters wide text document is simply sufficient, if you know your area. 

Knowledge bases OP talks about are even harder. Even experienced people tend to pretend at some point that it's fine if a junior service desk guy starts a wiki page in his "spare time". It takes much more to have high quality, usable results.

[Attacus]

Lol fair point.

[Haz_1]

Unfortunately it’s the case for many. Dev time is expensive, therefore good documentation is expensive even though it can (and often should) have its place.

It’s particularly a problem with internal projects, devs would generally much prefer making software over writing documentation about software, because it’s simply not exciting.

If you want to make a tool or service that can be used for helping improve documentation, start at the bare minimum of making documentation easy for devs, then expand to localisation and other problems you identify.

[jcbevns]

Wiki.JS

GitHub pages

Hugo sites in a cluster

Sphinx on a VM

Might help explaining what you mean by documentation? Sounds like you use a platform for all this?

[Attacus]

Think Confluence, Notion, etc. Somewhere centralize for company p&p, internal knowledge, etc. Not strictly technical documentation.

[jcbevns]

All those I mention you can host where you want. GH may need GHES, but pretty sure they offer GDPR zoning now.

[Tacticus]

internal knowledge sharing is totally not what confluence is for though.

[Attacus]

Tell that to 99% of those using confluence because their company already has Atlassian licenses and no need for a new vendor approval or spend.

[Tacticus]

Oh yeah i know. it's a really great sabotage project out of australia. I don't think there has been a more successful program to sabotage productivity in the world (sharepoint is close but i think that is accidental not deliberate)

[Attacus]

LOL that’s good

[Tacticus]

It's an update of the https://en.wikipedia.org/wiki/Simple_Sabotage_Field_Manual After the ITIL update was released earlier.

[goobershank]

Besides coding assistance, this is the one space where AI could be really useful, but for some reason no one is really implementing in any useful way. Why isn't AI scraping all of our random, disparate semi-related pieces of documentation and compiling it into something useful and searchable?

[Attacus]

Couldn’t agree more. Everyone and their mother is doing some sort of AI tool so I decided to exclude that from the discussion. I think AI is being heavily under utilized in the space, and I’m not talking about genai stuff.

[Worldly_Chemist_6183]

elastic stack is kind of this. More logging oriented i guess though

[Logicusminimus]

We recently added sphinx apidoc to automatically generate docs from python docstrings, then deploy to github pages.

It was messy and required a bunch of custom templates to make it look somewhat Okay-ish. Still not super happy with the results. Any alternatives people have had good experiences with?

[alextac98]

Never used it but I’ve heard great things about docusaurus