5 ms·
Confluence is where documentation goes to die.
by morkalork 3y ago
Confluence is where documentation goes to die.
- amai 3y agoRandom word documents in MS share point are the industry standard. Compared to that Confluence is a good tool with a great search.
- ben7799 3y agoThat's cause it's write-only. It's like: cat $DOCS > /dev/null rm $DOCS
- fuzzy2 3y agoWhere would it need to be not to die? Also, what kind of documentation? Technical? Or business?
- wwilim 3y agoIn the repo with the code, linked to from a sensible wiki that serves only as an index
- ta1243 3y agoThat's how our conflusence is used. Some departments do stupid things like duplicating information. We use confluence to describe the requirements, the concepts, then point to the right locations. Take IPs, some departments have pages and pages with the same IP, subnet, etc in
- morkalork 3y agoIn the repo with the code. Seeing commits where both the code and doc change together is a sight to behold.
- expazl 3y agoYou can do that in confluence.
- fuzzy2 3y agoOkay, but again, which documentation is that? Technical or business? Because I do not see business documentation evolving with code. And depending on what the code does, business documentation could be much more important than technical documentation.
- Washuu 3y agoConfluence search is terrible and never finds what I want even if I type in the exact title.
- gyudin 3y agoThey gave a try fixing it a while ago before giving up completely
- slingnow 3y agoWhat do you use for documentation? My experience with Confluence has been similarly bad.
- tomohawk 3y agomarkdown, in the repo with the code.
- throwawaaarrgh 3y agoTerrible experience for anyone who isn't already a contributor to that repo. Docs exist for people other than those that wrote them. The people that wrote them don't need to know the information, they already knew it.
- dingnuts 3y agoIt's the worst documentation tool, except all the others. Seriously though, what is better?
- sa46 3y agoI’ve been pretty happy with Slab. Straightforward shared wiki with a good editor, governance, and integrations. https://slab.com/ https://slab.com/ I tried using README files in the repo but there’s far too much friction to get most folks to bother. Google Docs tend to disappear content due to a lack of structure.
- morkalork 3y agoSpeaking of Google docs, I just now had the joy of talking to a co-worker while trying to figure out the source of truth for something and we spent 10 minutes thinking we were looking at the same doc when in fact we were not! The owner had made and shared multiple slightly different copies.
- paiute 3y agoAt my current job, i need to make a jira ticket, a branch, do a live review… all to change a minor thing in a README
- neilkk 3y agoThat sounds bad, but sometimes it makes sense to optimise the process for midsize changes. The vast majority of useful work is done in midsize changes. Lots of people like to generate a flurry of tiny commits but it's not necessarily the most productive way to work, even without much overhead per change. You can always bundle tiny changes together until it's worth it for you and other people like the reviewer to do the parts that don't scale downwards.
- nomel 3y ago> I tried using README files in the repo but there’s far too much friction I have confluence links in my Readme, which seems to be a pretty good balance, since it's physically impossible for people to use a search bar in a wiki.
- circusfly 3y agoI much prefer Confluence to something like myriad Word and Excel sheets of uncanny versions floating around mostly unknown Sharepoint locations.
- rightbyte 3y agoAt least you can search more or less properly in network folders. At my old work I usually left a search going from the root network folder over the weekend, scanning for some keywords, when I needed a doc none knew where it was or if it existed at all. There was a parallel documentation system from IBM that didn't work, where the canonical docs should be. But you more or less had to know the document ID to query it. So most documents were also in the network folders spread out between hundred project folders and meeting folders.
- ClimaxGravely 3y agoI loathe confluence, tried to get a markdown plugin around 2016 and IIRC the charge was 5$ per person at the company per month. For what it's worth it's a lot better than it was in 2016 but I'm still not a fan.