Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: How do you organize software documentation at work?

news.ycombinator.com

Post reply on HN
Print view View original

51–60 of 93 posts

Re: Ask HN: How do you organize software documentation at work?

#51

Post by coldpie »

raziel2p wrote: post #43
coldpie wrote: post #29

Earlier quoted context omitted.

The same tool you use for merging code, with the same ownership & maintainer model. In our case, that's git, and our docs live in markdown files in a docs/ folder.

So in order to find documentation, you need to know which repo to look in? How do you deal with cross-cutting concerns, docs that span multiple code repositories?

Yeah, you'll have to sit down and answer that question. Where do docs live? Who is responsible for maintaining them? Wikis let you skip all that, throw the docs into the dumpster, and forget about it until some poor soul comes along and asks a question that's 5 years out of date because they found it on the wiki. Wikis are not a solution, they're giving up.

Re: Ask HN: How do you organize software documentation at work?

#53

Post by eitland »

madduci wrote: post #25
coldpie wrote: post #4

Never use a wiki for anything. Wikis are the number one worst form of documentation. They are worse than no documentation. Wikis explicitly destroy the concept of ownership and responsibility, and without those, what you get is a big pile of outdated, unorganized trash that no one maintains. Destroy wikis.

So stop using Confluence?

I think that is a better idea than demanding everyone ditching all wikis.

Dokuwiki for example has a sane, plain text format. It can be extended relatively easily compared to Confluence (I have tried both).

Unlike certain other wikis it has access control and unlike Confluence you can edit a single paragraph or section at a time.

And finally, it is actually a wiki, wiki originally meant "quick" I think and I think calling Confluence a wiki in that context is somewhat ironic.

Re: Ask HN: How do you organize software documentation at work?

#54

Post by mattbrewsbytes »

coldpie wrote: post #29
packetlost wrote: post #5

Earlier quoted context omitted.

So what do you use instead?

The same tool you use for merging code, with the same ownership & maintainer model. In our case, that's git, and our docs live in markdown files in a docs/ folder.

> Five years and 80% employee turnover from now, your git docs will be a completely unsearchable pile of outdated trash from employees who don't work there anymore

Throwing your own other comment back at ya :D

If docs aren't maintained and curated then it doesn't matter if they are in a wiki, word docs, printed pages in a file cabinet or in the repository as markdown files. Getting team discipline around updating docs is the solution, the place where they are stored is sort of trivial if that discipline exists (fwiw, I've yet to see that discipline).

Re: Ask HN: How do you organize software documentation at work?

#55

Post by troyvit »

Horribly. We use Confluence for much of our documentation, but we can't afford the license to give everybody access to the documentation who needs it, so often we'll be copying data out of Confluence and into google docs. There's an export for that in Confluence but it's buggy on larger documents and often it's just faster to do it manually.

Meanwhile over in google docs it's a trash fire. There's no organization, just documents. At least sharing is possible, and the collaboration is clutch, but documents are copied, those copied edited, then not shared with the originals. It just goes on and on.

Then we have an intranet based documentation system called Papyrs. At least it's a wiki, but nobody maintains it, and search is best described as enabling users to rule out what they're looking for rather than find what they are.

Whatever you do, don't do what we did :)

EDIT: mentioned collaborative nature of google docs

Re: Ask HN: How do you organize software documentation at work?

#57

Post by frfl »

troyvit wrote: post #55

Horribly. We use Confluence for much of our documentation, but we can't afford the license to give everybody access to the documentation who needs it, so often we'll be copying data out of Confluence and into google docs. There's an export for that in Confluence but it's buggy on larger documents and often it's just faster to do it manually. Meanwhile over in google docs it's a trash fire. There's no organization, ju…

Honestly github isn't that bad as a wiki. You get versioning, rich markdown, collaboration, commenting, and it can just be markdown, not some proprietary syntax. And editing right in your browser for non-technical folk, get tell them committing = saving. Might have to manually upload images though. But I recall github supports mermaid diagrams [1].

[1]: https://docs.github.com/en/get-started/writing-on-github/wor...

Re: Ask HN: How do you organize software documentation at work?

#58

Post by quectophoton »

dewey wrote: post #19

Code comments + Slack. GitHub and Slack search are great if you know how to use them and I have yet to find something I couldn’t answer with these tools. People like to say “Slack isn’t documentation” but in reality it’s a better documentation than some outdated Wiki nobody is touching.

A Slack channel where an issue was discussed publicly, with both the debugging process and the final solution, is priceless. But it only happens with people who also think that.

My experience has been that most info is lost in DMs and video calls. When I helped coworkers, I had to be the one posting the info on public channels if I didn't want to be solving the same problem next week, next month, and half a year later.

Re: Ask HN: How do you organize software documentation at work?

#59

Post by coldpie »

mattbrewsbytes wrote: post #54
coldpie wrote: post #29

Earlier quoted context omitted.

The same tool you use for merging code, with the same ownership & maintainer model. In our case, that's git, and our docs live in markdown files in a docs/ folder.

> Five years and 80% employee turnover from now, your git docs will be a completely unsearchable pile of outdated trash from employees who don't work there anymore Throwing your own other comment back at ya :D If docs aren't maintained and curated then it doesn't matter if they are in a wiki, word docs, printed pages in a file cabinet or in the repository as markdown files. Getting team discipline around updating doc…

Yeah of course you can have bad docs in any system. But wikis actively encourage a bad ownership model (i.e. none). You could put in a bunch of work to build up an ownership and change review system around a wiki, I guess, but we already have tools for that. Use those instead!

Re: Ask HN: How do you organize software documentation at work?

#60

Post by ramses0 »

coldpie wrote: post #4

Never use a wiki for anything. Wikis are the number one worst form of documentation. They are worse than no documentation. Wikis explicitly destroy the concept of ownership and responsibility, and without those, what you get is a big pile of outdated, unorganized trash that no one maintains. Destroy wikis.

I will counterpoint slightly to this... I'm currently trying to set up a wiki for my house documentation (eg: TechStack, QuarterlyMaintenance, ValuableAssets, BackupRestore, HomeAutomation, etc...).

When there's a very limited set of curators, a specific topic, and a self-incentive to keep things "up-to-date" wiki's can be a great choice... mostly as like a knowledge base or internal glossary/dictionary.

For true "documentation" (if you don't take the wiki as a whole), and in the corporate world, I agree with the issues against using wiki's.

Post reply on HN