5 ms·
The most frustrating thing about working remote was the complete lack of documentation around anything -- meetings, requirements, internal frameworks/libraries,
by dandersh 10y ago
The most frustrating thing about working remote was the complete lack of documentation around anything -- meetings, requirements, internal frameworks/libraries, etc. Good for them for emphasizing documentation.
I lost track of the amount of times I was told to "look at the source code" when asking about documentation for the internal framework.
Also fun was being assigned a feature and having it's functionality explained over the phone, with any subsequent follow-up being met with "Didn't we already talk about this"?
I never would have thought that a remote based team would have the worst documentation out of anywhere I've worked, but that's exactly what happened.
- bgaluszka 10y ago> I lost track of the amount of times I was told to "look at the source code" when asking about documentation for the internal framework. Can you elaborate on this one? This is my preferred way.
- overcast 10y agoYou prefer just being handed a pile of code, rather than documentation on how to use it? please.
- bgaluszka 10y agoIn case where I work for a given company and it's internal tool, always.
- crpatino 10y agoImagine this scenario. You work on product A. Your VP of very important things declares that every product should use library L. Library L has been designed to incestously interact with product D and makes a bunch of assumptions about what the "working environment" should be. Teams B and C have already made the transition, so L made some kludgy APIs to make B and C interaction possible, though it is maintained with low priority because everybody knows D is the money maker. Both B and C have a bunch of assumptions in common that A does not share, and they both had to compromise and emulate D environment to some exent. You are given L binaries, a few toy examples of how to use the most basic functionality in L, and access to B codebase. L codebase does not use the same source control system, so you don't even know where to begin looking for their code. Please keep in mind that your manager does not expect you to learn all the inner workings of L. Your priority task is to use L to support some new feature in A. You still have a number of other tasks to accomplish in A that are not related to L, and some of those might raise in priority with little or no notice. Do you still think it is a good idea to just browse L code, without knowing how large (or well writen) it is?
- bgaluszka 10y agoNote that I said it's my preferred way but by any means that doesn't mean that if there is some documentation I won't look at it.
- crpatino 10y agoThe fact that it is your preferred way tells me that the only internal frameworks you have encountered in your career were tidy, tiny, and self contained. Having struggled with very large tools that were anything-but, I beg to differ... but I guess it is a matter of personal experiences.
- overcast 10y agoAt best this is nonsensical, at worst, you're trolling all of us.
- deleted 10y ago[deleted]
- wazanator 10y agoProper documentation that explains what the code should do, how it does it, and if there are any known bugs is a lot faster (IMO) to read them to open a file to try and parse what the people who worked on it intended and what all its doing. Add in cases where people go crazy with inheritance and you need it or else you have no way of knowing what all it is this new class can do.
- dandersh 10y agoInstead of being able to quickly peruse docs to see if a method existed and what it took/returned, I would be directed to dig through source code to see if it exists and what it did. This is basic API doc work. This meant something that should have been fairly quick took significantly longer. Then there were times when I did dig through to understand why something worked. When I pointed out that something should be done differently (an id-lookup done hierarchal instead of flat) I was told "Oh that's deprecated, you're not supposed to be using that anyways". And how exactly am I supposed to know that? Ultimately it was a frustrating way to spend a lot of time.
- lallysingh 10y agoExactly. You can write it down once or have people figure it out independently many times over. Documentation saves engineering time.
- SpaceDingus9000 10y agoI worked at a place with remote and onsite employees, and I think two of major reasons it worked is because we had a habit of documenting all designs and projects in a wiki, and used Skype at all of our meetings (while sending an invite out before hand to anyone tangentially related so they could sit in if they felt the need to). The wiki would inevitably get out of date, but it usually gave you a good big picture and the edit history let you know who to track down for questions. All of the development teams were also on Slack, and many people tended to have those quick side conversations online instead of in person, so there was a public searchable record and you could jump in more easily.
- purerandomness 10y agoYou seem to work at a horrible place, with abrasive characters. It begins with the fact that the company's code needs documentation. I'm a big proponent of Robert C. Martin's "Clean Code" and the idea that code should read like prose - by reading the code, its purpose and ideas should come across naturally. It ends with people asking "Didn't we already talk about this?". Is this your first job? Don't let yourself get treated like this.
- csours 10y ago> You seem to work at a horrible place, with abrasive characters. Or a normal place with poor-mediocre leadership. Documentation doesn't happen by magic, and documentation is a skill. If it's not a priority from management, folks will be heads down getting their own tasks done, not thinking about what the other person/team needs.
- douche 10y agoTo be fair, this happens in dysfunctional organizations that are all on-site, too. There's no good excuse for being that disorganized, but it happens all too often.