71–80 of 110 posts
Create small teams that work well together, give them lots of responsibility and autonomy, and let them work on the things they really care about deeply.
This is a document which exists to link to other documents. I use a shared Google Doc for it (which is almost equivalent to a wiki).
Since it's a document (and not a folder or a spreadsheet) each linked document can be combined with some explanatory context - is the document current? What does it cover? etc.
I also like splitting my doc-of-docs into different headings, for example:
Current
Outdated
Related projects from other teams
The key benefit of the doc-of-docs approach is that the answer to EVERY question about "where can I find documentation for X" is "Look in the doc-of-docs". And the follow-up answer if they don't find it there is "Go and find that document, then add it to the doc-of-docs".
Recently we started using Slinkky https://www.slinkky.com . It makes organizing information for your team and company really simple. There's a 30 day trial for startups so there's no loss if it doesn't work out. You can collaborate on personal boards with coworkers and add team spaces for shared content. You can restrict permission by user so only admins and managers can add content to team boards.
Earlier quoted context omitted.
Could you tell us more about how your book is relevant to the topic at hand? I've tried to read up on information operations, albeit in a different context.
Sure. I wasn't looking to pump the book, it was just weird. I have spent my career with technology teams, either 2 guys in a closet or 40-thousand people working on multi-year, multi-billion-dollar efforts. Something weird happens between the 2-guys scenario and the 40k version: critical information stops moving around effectively. Many times big organizations seem to exist and profit more out of a sense of inertia t…
Best of luck with the book!
Some other things I've learned... Wiki's suck, they become stale, they are disorganized, very informal. I recommend just keeping big ass user guides (can be different ones for different systems or even user guides about procedures that are not about products) using a well-organized documentation system and a well-kept table of contents. Don't waste tech writers on internal docs. They'll spend half their time asking the dev anyways, it will get stale, and asking a dev to write something is not asking too much. Keep the docs close to the code, but not in the code like comments. Docs close to the code can let people have less friction between code and doc commits. Each non-trivial repo should have a manual (a.k.a. user guide) anyways. And if you have to, say, grab a bunch of RST files from a few disparate Sphinx doc locations, so be it.
I personally use documentation as a point of pride. My favorite part of any project is documenting the awesomeness I did. I just make sure I order it in a reasonable order and don't bloviate.
I've found that the tool doesn't matter as much as the company culture. You need to foster a culture of documentation for EVERYTHING. It doesn't matter if you have the best tools in the world if nobody uses them. Too often this falls by the wayside because documentation of processes and preserving institutional knowledge, while extremely important, isn't the type of work that gets recognized or rewarded. If anyone ca…
I think the tool choice doesn't matter much but having a well defined tool or process helps a lot. In my company it's never clear where to our documentation or where to find it. So every time you have to think about this and often don't get started . In my team we have started using OneNote for everything and now we always know where to put things and where to find them. Suddenly documentation is getting better and is actually useful because you can find what you need.
Previously we used SharePoint and data just went into it and disappeared to never be seen again. Totally useless.
Now, documenting things is a different story...as gringoDan pointed out here (https://news.ycombinator.com/item?id=16811654), whether or not your documentation process/tooling gets anything done is directly 1-to-1 correlated with company culture on documentation. I've personally tried numerous times to get documentation going, and it always fails because no one keeps up with it.
I've found that the tool doesn't matter as much as the company culture. You need to foster a culture of documentation for EVERYTHING. It doesn't matter if you have the best tools in the world if nobody uses them. Too often this falls by the wayside because documentation of processes and preserving institutional knowledge, while extremely important, isn't the type of work that gets recognized or rewarded. If anyone ca…
I would say that the culture + making sure your projects and teams are well organized is the key to success. In addition, I'd recommend to follow some protocol when documenting things. This will make both writing and reading a less intense and more predictable task, resulting to a better overall experience.
Try https://www.notion.so ! It combines docs, wikis, and todos; it's collaborative, and it's beautifully designed. It's perfect for building knowledge bases for teams. (Disclaimer / I worked there in the past)
At a glance, it looks like a product that's stored on the company's servers. Why would any company, startup or dinosaur, want to put their knowledge base and documentation in the hand of a new pretty and fancy product that might fold next month? There's no Linux download, no github, and especially, no server - I stay away from products like that, sorry.