![]() The Collection extension did that, though, but Wikimedia's weird behavior around it and their multiple failed attempts at choosing a tech stack for output - OCG/ZIM, PoD/PediaPress, Electron (not that one)/Proton - much less the next step of building that functionality into a usable feature in MW, turned me off from trying. It wasn't just technically complex (no users wanted to learn how to do it, they wanted one person to do it for them), it also didn't do the one thing most people wanted it to do. But it still isn't easy to build an ordered, hierarchical, book-like structure with book-like output, which was a constant request. I enjoy Cargo and DPL, they're powerful and great tools for automatically aggregating and filtering content, and I used both of them a lot at a MW that I was an admin on for several years. That is one repeated problem we face in the Atlassian stack (well a source of their income…)- even a seemingly cheap plugin (extension or whatever they’re called) ends up in the person suggesting how to ‘work smart/not hard’ having to find the funding typically a two digit thousands of € or year (thus I never bother with that anymore :( Unfortunately we did not implement the plug-in as we have too many eggs in the Jira basket (+1.000 users) which have the unfortunate side effect that the licensing price is derived from the +1000 users even though only the much lower number of devs would use it. So conceptually the same as you’re solution -) docs are easy to update (as you can use any editor: vi, emacs, IDE’s etc) docs get exposed in Confluence (thus is accessible for the business folks that does not do git) docs stays in the repo (thus is much more likely to actually get updated) I once found a plug-in that did almost the same, allowed Confluence to read and render markdown files directly from (private) GitHub repos thus allowing me to get the best of both worlds! I face the same problem as our company is heavily using the atlassian products (Jira/Confluence…) ![]() Even if you have the people on a team with the aptitude for it, it's usually low priority in every work cycle, and the first casualty when trying to hit deadlines. it's a lot harder than it might seem when first considering it. On the whole, keep written docs both updated and useful and findable to a growing number of people with disparate needs and different contexts and backgrounds. I suspect that if those folks moved on, those docs may slowly rot. Discoverability on the size of that project (and this is 'only' 5 years old ~80 people) was just useless.Ī handful of folks did keep 'onboarding' stuff relatively up to date, but it was less than a year old at that point. Few people ever looked at it for anything more than "recent updates" to see what's changed in the last 2-3 weeks. No one on the dev team bothered to ever look there for anything, because it was simply pointless. It was as much a problem of a growing set of contributors and growing departments than anything else, but there was a new 'direction' every 6-9 months (when new folks would come in) and "this worked at my old company" so they'd document stuff however they wanted. ![]() When updated, you wouldn't necessarily know if you needed to look through 5 versions to see earlier thinking, or which links to 'updates' confluence pages you needed to trawl through. ![]() The closest I came to understanding it was the confluence docs were always initial plans, but were rarely updated. ![]() I was on a team that had everything in confluence, and everything was impossible to find. Those doc files may reference external items like confluence pages or specific tracking ticket/URLs that relate to the code at hand. Middle ground I've found on some projects: very detailed code/data-oriented notes are in markdown in the repo, tied to a PR. I've taken to putting a link to the Confluence docs ![]()
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |