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

Ask HN: Organizing company knowledge?

news.ycombinator.com

Post reply on HN
Print view View original

51–60 of 110 posts

Re: Ask HN: Organizing company knowledge?

#51

Post by methyl »

dx034 wrote: post #40
hellofunk wrote: post #30

Earlier quoted context omitted.

> Each line of code was documented Wow. Every line. There is such a thing as too many comments or too liberal use of comments in code.

Not if the system fails on a Monday morning at 3am after 20 years without issues and needs to be fixed before the business opens. Having comments for every line helps fixing it dramatically. For most code it will be overkill but there are some companies where it's integral for core systems.

> Having comments for every line helps fixing it dramatically.

That’s only true if comments are kept up-to-date. More often than not, they get out of sync with the code itself, causing even more confusion.

Re: Ask HN: Organizing company knowledge?

#52

Post by kevingoslar »

In addition to the right culture, great platforms enable great ecosystems. I have found that putting everything as Markdown on a collaboration platform like Github/GitLab works really well and enables collaboration in a number of ways:

- people don't feel awkward to modify other people's content because there is a collaboration and review process in the form of pull requests

- you can assign different people to oversee different parts of the knowledge base. They make sure the organization of the knowledge base doesn't get messed up by reviewing changes of other people to it.

- you can keep others in the loop about important updates (big and small) by tagging them in pull requests

- verification can be automated via bots and CI, for example using https://github.com/originate/text-runner

Re: Ask HN: Organizing company knowledge?

#53

Post by pjc50 »

hellofunk wrote: post #30
thisisit wrote: post #27

Earlier quoted context omitted.

This cannot be stressed enough. Often I see managers talk about Sharepoint or some wiki type tool within the company but then the culture of documentation is missing. The best case scenario I found was in a bank. Each line of code was documented and rationale explained in plain english. This way hypothetically even a newbie could run the system. While different places have different issues, I found that the quality o…

> Each line of code was documented Wow. Every line. There is such a thing as too many comments or too liberal use of comments in code.

I doubt they meant literally every line, but for some of the more esoteric systems an average of one line of comment for line of code could be worthwhile. Paragraph of explanation, paragraph of code. I'm thinking of things like assembler or COBOL here.

APL/J are highly compressed and any reasonable explanation would require more than one line of documentation per line of code. I know there's some J in financial institutions.

Re: Ask HN: Organizing company knowledge?

#54

Post by Pamar »

dx034 wrote: post #40
hellofunk wrote: post #30

Earlier quoted context omitted.

> Each line of code was documented Wow. Every line. There is such a thing as too many comments or too liberal use of comments in code.

Not if the system fails on a Monday morning at 3am after 20 years without issues and needs to be fixed before the business opens. Having comments for every line helps fixing it dramatically. For most code it will be overkill but there are some companies where it's integral for core systems.

Honestly, these kind of problems are often due to unplanned/unexpected events (disk full, wrong permissions on a folder, OS updates correcting old bugs you have coded around) where having line-by-line comments would not help much if at all.

I would love to work in a place where documentation was cosidered a valuable asset, but I think that your example is off mark.

Re: Ask HN: Organizing company knowledge?

#55

Post by arsalanb »

I'm working on something that aims to make this easier from a more ground-up perspective, but it is many years away from when we can say this problem has been solved completely. Here's something I've learnt in the process (as gringoDan said in a comment on this tread) company culture is the fundamental requirement. The limitation with organisation tools is that they amplify your company behaviour digitally.

If your company does not prioritise a written culture, then there is no tool that can come in and magically do it for you. Your tools will only amplify this phenomena (your team will use the tools for some time, and then quickly think of it as "another thing to do" when the shine wears off and stop using them)

This is because of the way current tools are set up. I have seen companies hire interns to help keep their internal knowledge updated. Despite this, there is always some document to update. I view updating documents as work that is required to keep other (perhaps more "important") work seamless. I can draw a comparison between maintaining internal documentation and writing unit tests (both equally important, while being underrated and easily postponed for later) At scale it either compounds to a technical debt and can bring the whole company to a halt momentarily.

Re: Ask HN: Organizing company knowledge?

#57

Post by groar »

We started using Slite http://slite.com/ 6 months ago with great success. We previously used Atlassian Confluence for our internal knowledge database, and it resulted in very static content and poor adoption. Slite is a much better choice: we use it for "static" company knowledge (like onboarding, processes, etc.), but also for most of our dynamic content (meeting notes, document drafting, sales support documentation, etc.).

Many people (including dev) use it on a daily basis, and most people on a weekly basis.

Definitely recommend.

Re: Ask HN: Organizing company knowledge?

#58

Post by thisisit »

hellofunk wrote: post #30
thisisit wrote: post #27

Earlier quoted context omitted.

This cannot be stressed enough. Often I see managers talk about Sharepoint or some wiki type tool within the company but then the culture of documentation is missing. The best case scenario I found was in a bank. Each line of code was documented and rationale explained in plain english. This way hypothetically even a newbie could run the system. While different places have different issues, I found that the quality o…

> Each line of code was documented Wow. Every line. There is such a thing as too many comments or too liberal use of comments in code.

My bad, I should have been clearer. What I meant to say is each block of code was documented. So a logic change wasn't accompanied by line by line commenting rather a block comment explaining who, what, why and when of the change. The commenting guidelines were well defined too.

Re: Ask HN: Organizing company knowledge?

#59

Post by DanielBMarkham »

arsalanb wrote: post #45
DanielBMarkham wrote: post #21

For me this was an oddly-timed AskHN. I am publishing a book on this exact topic in the next week or so. https://leanpub.com/info-ops

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 than strategy.

Looking at this, over the last several years I've been trying to identify why some organizations do well in how they handle information flow and how some (most) organizations don't.

There is a ton of detail here. It encompasses everything from Lean Startup to Business Modeling and Extreme Programming. (Way too much for an HN comment, sadly!) There are a few folks talking about how to think about information at the meta level, but not a lot. Happy to point folks to some free online resources. Just let me know specifically what you're looking for.

Re: Ask HN: Organizing company knowledge?

#60

Post by DanielBMarkham »

nabeards wrote: post #56
DanielBMarkham wrote: post #21

For me this was an oddly-timed AskHN. I am publishing a book on this exact topic in the next week or so. https://leanpub.com/info-ops

Do you have a summary for it?

Build the right thing.

We spend so much time and effort on building-things-right. It's much more important to build the right thing. Usually (not always) boils down to information flow and feedback loops.

I'm so far in the weeds right now with the book publish date coming up it's for me to provide a good overview. Here are some comments from my alpha reader group (I do not know these people and they are not paid in any way for these recommendations)

Hey Daniel,

Got info about second part of Info-Ops, will get to the details later today. But I just wanted to give you quick info (while not very useful at this stage I assume, but still...) - few days ago I finished the book. I loved it. It's written in simple language, easy to understand and digest even for not-native speaker like myself. So that's very good.

The bad: I wish I read it two-three years ago, would make me much better software developer!"

Daniel,

"You know, when I first got to know you, I thought you were a funny guy, but arrogant. (Yes, I am aware of the irony.) After reading the beginning of this book, I realize you're not actually arrogant - just really fucking capable. This may be the best book about process analysis I've ever read. OK, I have to admit it may actually have been the only book about process analysis I've ever read, so there's an inherent grain of salt there, but damn. This stuff is truly fantastic. Very, very well-considered and thought-provoking. I am truly and unironically happy you've given me the opportunity to read it...Seriously, I find this roughly on par, in its level of thought-provocation, as Doug Hofstadter's work. I might have a slightly weird way of looking at it, so don't derive any expectation of universal acclaim from it, but I do mean it. Damn fine work."

"Daniel. Wow. I didn't know you had it in you. I'm eager to keep moving forward. ... I like your approach and wondering if you can or were at all all looking to at some point to speak/teach/consult on the topic? (We could use at current client!)"

"I'm Ola Ellnestam a software developer and team coach/lead. My job is to balance software development with regards to process, delivery and collaboration. I didn't know what to expect from Info-Ops, I thought it had to do with DevOps and information. A few chapters in though I realized it gives the reader a concrete way of looking at, understanding and in a way, manage the information that flows through a software development effort. It helped me understand underlying problems with that flow and how to deal them. It also gave me new ideas on how to work with semantics in software development in a more pragmatic way. If you want to know how to create a shared mental model in your team and beyond, read this book and I am sure you can become the grease between business and tech."

Post reply on HN