211–220 of 220 posts
The culling of deprecated stuff is too hard. The incentives are all wrong. And it's drudge work.
My proposal:
We need to time box and auto expire everything. Like TTL leases. Renew leases on active work. Everything else enters the grooming process.
Have stages, like Trash Bin vs hard delete, to minimize impact.
Automate everything that can be automated. Avoid setting up things using GUIs. Starting a set of services should be as simple as "docker-compose up", building should be as simple as "make", checking out the code should be as simple as "git clone", etc. You shouldn't need a shitload of wiki checklists that describe how to install dependencies and how to check out all the git-directories with correct versions relative…
Write write write and keep writing. Then expect to do 10x as much reading. It's exhausting and definitely relies heavily on employees' writing and reading comprehension skills. HashiCorp produces a mind boggling amount of prose (non-code text). Every employee can read every RFC going back to the first sketch of terraform which was completely rewritten in a second revision. Mailing lists are alive and well. PR descrip…
It’s demoralizing to write write write when you know no one is going to read, and if you link them something more than 100 words long they’ll ask for a meeting instead.
Earlier quoted context omitted.
> Because if you create different solutions to meet the publishing preferences of different groups inside the organisation, then I don’t think you’re meeting the goal of institutionalizing the knowledge. High-level project descriptions don't belong in code. It's a different beast, and doesn't belong in the repo alongside the implementation. Non-technical users probably shouldn't even have repo access. In-code comment…
> It's a different beast, and doesn't belong in the repo alongside the implementation. That's just, like, your opinion, MaxBarraclough. If they aren't in the repo, they're never going to get updated, and as a result they will be outdated within 6 months on any project that's moving anywhere. I prioritize freshness of documentation against most other attributes. It does nobody any good to have documentation for the sy…
> If they aren't in the repo, they're never going to get updated
Not so. The Qt folks use a separate repo for their documentation. [0]
My point earlier was that high-level documentation is a separate project than the implementation. You could keep the high-level documentation documents in the same repo as the implementation if you want, that's just a monorepo.
https://slab.com/blog/knowledge-hoarding/
It's not a direct pitch to use Slab. In it we talk about the three reasons we discovered most folks hoard knowledge:
1. Leverage: If an employee hoards their knowledge, they may feel like they are irreplaceable. 2. Fear: Putting yourself out there can be intimidating. What if colleagues or supervisors respond with negative feedback? 3. Competition: If your workplace rewards personal triumphs over shared victories, employees are less likely to want to share their "secrets."
Also, no matter what documentation tool you use, it's worth reading this first: https://slab.com/blog/documentation-tools/
Many teams initially gravitate toward more generic document editors (Google Docs) as their first team wiki, for logical reasons:
- These editors are familiar to most people, meaning they can be easier to adopt across an organization - Most companies already use (and pay for) at least one of these tools - Teams realize the need for documentation, but aren't thinking of how their documentation tool will scale alongside their business
But there are some issues with these document editors that teams discover as they grow. This article dives deep into those shortcomings. Here are both article links again, and good luck!
1. https://slab.com/blog/knowledge-hoarding/ 2. https://slab.com/blog/documentation-tools/
Earlier quoted context omitted.
I don't know what the infatuation with markdown is beyond web publishing. Wysiwyg documents have been a solved problem for decades. Use what works on your platform. Markdown is fine until you realize you would like to have figures, images and tables. I don't want to spend my time over trite details of a text based markup when I could spend it actually productively. At that point it's way over easier to use a text pro…
This. Markdown is great, but I’ve seen so much time wasted on Rube Goldberg solutions that would be trivially addressed by using less cool solutions like Word or GDocs.
Earlier quoted context omitted.
Your position is reasonable. The value of spending time on documentation in a vaguely specified and frantically written web app is not the same as, e.g. writing documentation for the frameworks that drive that same application.
Even with the most frantic half effort of a project, its helpful to give the context of why you are doing it, why you approached the project this way, and why you ended up not going with another approach. Maybe you did try what should have been the best approach at first, and it didn't work right, so you had to do something not as good but good enough. Then in the future someone decides to try to redo what you've don…