News for hackers. Stuff that matters.
Re:Mistakes I've Made as an Engineering Manager by taftster on Sunday February 21, 2021 @04:33PM (#26217453)
I respectfully disagree to an extent. I think most/all documentation ends up rotting and being ignored. If you take the time to write it down, it doesn't mean that others will take the time to read it or refer to it.

I think it's better to just continually verbalize any "core values" with your team as you go day-to-day. Thinking that you've written it down inside of an organized GDocs is not much different than having sent it via email (the location to retrieve it just changes).

Re:Mistakes I've Made as an Engineering Manager by y2bd on Sunday February 21, 2021 @06:17PM (#26218347)
There are two ways that I interpret this

* What’s being written down isn’t valuable, so people don’t trust the wiki to have valuable information and therefore ignore it.

* What’s being written down is valuable, but people have been trained to get information elsewhere and therefore don’t bother going to the wiki

I don’t really know how to address the former (“write better!” isn’t very actionable advice), but in my work I see the latter a lot, and the only way you can fix it is socially—if someone asks you a question that’s answered in the wiki, you have to tell them “read the wiki” instead of giving them the answer yourself.

People are lazy, and it’s almost always easier in the short term to just ask someone for the answer instead of looking it up yourself.

Re:Mistakes I've Made as an Engineering Manager by Guvante on Sunday February 21, 2021 @06:39PM (#26218512)
If we get better search systems I would be totally on board. But most knowledge base systems have a hard time finding similes for words let alone sorting articles containing multiple keywords in a useful order.

Having the information written down is important if nothing else than a source of reasoning going forward (people tend to remember do X but rarely why in my experience). However saying that asking a coworker is a bad thing is giving way too much credit to the documentation.

Additionally if you are talking about anything but the most basic associations talking with people is a good thing anyway as you can discuss your idea and see if there are problems the documentation couldn't tell you about because said problem would be listed in a different place.

Re:Mistakes I've Made as an Engineering Manager by y2bd on Sunday February 21, 2021 @06:52PM (#26218599)
Sure, I should make clear: documentation/wikis are best for who/what/when/where of things like

- What permissions do I need to contribute code to this repo

- Where are the telemetry tables for X event

- Who’s the manager for project Y

- When will my commit make it into production

For the whys and hows that often warrant discussion, while I still think you should have basics documented (How do I add a new screen to this app, why do we call into this proxy service, etc) so that folks have a starting place, and then pursue actual discussion.

Even if the wikis are literally just the most basic associations, I still believe that would clear up a ton of repeated and honestly unproductive discussion time.

Re:Mistakes I've Made as an Engineering Manager by lumost on Sunday February 21, 2021 @11:54PM (#26221006)
I've had a funny observation over the years. The more refined the wiki, the worse the code/ops are.

Good ops and code are usually to some extent self-documenting. If you had a wiki with 20 steps to perform some task, maybe the answer is that the process needs to be simplified.

Re:Mistakes I've Made as an Engineering Manager by bobthebuilders on Monday February 22, 2021 @12:21AM (#26221154)
I've noticed it a lot of times in legacy systems. There's often a page with 20 different idiosyncrasies that you have to deal with, and the code is too critical to update even with comments
Re:Mistakes I've Made as an Engineering Manager by Kranar on Sunday February 21, 2021 @04:43PM (#26217546)
This might be fine at a smaller company, but as you grow, having people verbalize these things results in slight variations that over time grow into very big inconsistencies.

Setting up MediaWiki and throwing it up on a Linode server costs 20 bucks a month and can be deployed from a Docker image in roughly 15-20 minutes. It can referenced by everyone, anyone can contribute to it with a full audit of changes, and it's easily searchable.

I use it to document technical and non-technical things like company policies, work flow processes, security practices, coding style, pretty much anything. New employees have a standardized on-boarding process that is clearly documented step by step for them to get setup with everything they need to start being productive by their second day of working here.

It's actually fairly low effort to do this and is a lot easier than having a bunch of people have to remember God knows what and when, or forgetting and then having to ask someone else who may have a vague recollection of it.

An authoritative source of knowledge that everyone has access to and anyone can contribute to is worth setting up.

Re:Mistakes I've Made as an Engineering Manager by steve_g on Tuesday February 23, 2021 @07:38AM (#26236590)
I got really excited about the Linode/mediawiki solution. We're looking at Jira/Confluence right now, and it seems pretty heavyweight.

But then I remembered nothing takes 20 minutes. I'll bet it takes 20 minutes to set up the wikimedia server and then 4 days of Googling to get our single sign-on to work. We'll have to figure out what to do with backups. Plus we'll need to document the documentation process itself and do the painful change management with the organization. Finally, we don't use Linux, so it would probably take more than 20 minutes to figure this stuff out.

It's a great idea, but it's a non-trivial amount of work. Not that I disagree with your approach, but I'm saddened when I think about how to get there.

Re:Mistakes I've Made as an Engineering Manager by taneq on Monday February 22, 2021 @01:08AM (#26221373)
I do the same, even just for my own notes. That way it's all there, accessible, searchable, in the same place. Far better than everyone squirreling their own critical data away in a different tree-trunk.
Re:Mistakes I've Made as an Engineering Manager by tharkun__ on Sunday February 21, 2021 @07:08PM (#26218733)
Why would I want something like that on an external resource like a wiki? What's wrong with having it right there in the source in a README.md?

Easily searchable on my machine with grep or ack or whatever you use. Many tools (such as github, many IDEs etc.) open it up with when you open up the project, including formatting it. If you really want, you can serve it up somewhere via HTTP. When something changes I can commit it right with the changes I'm making.

Re:Mistakes I've Made as an Engineering Manager by GSGBen on Sunday February 21, 2021 @08:24PM (#26219517)
This works for developers but excludes large swathes of other stakeholders, some with huge amounts of business/process knowledge. MediaWiki supports WYSIWYG via VisualEditor, which increases usage from others (and has the benefit of making tables much more pleasant to work with).
Re:Mistakes I've Made as an Engineering Manager by tharkun__ on Sunday February 21, 2021 @08:38PM (#26219660)
I completely agree with you for documentation that is not developer centric. A wiki and a WYSIWYG editor is the way to go there. Though it is funny to see PMs and other people fight with say the Confluence editor (that's what I'm stuck with at the moment @work and they've recently effed up the Jira editors as well in favour of non-developers). It's abysmal and since they changed it to remove proper wiki syntax editing I can't even really fix things for them easily and have to use workarounds myself instead of teaching them a little bit of wiki markup syntax from time to time or using it myself to fix things. It's like MS Word and everyone learning all the workarounds of how to undo weird formatting or fix documents. What was wrong with LaTeX? :)

That is absolutely not what we're talking about here though. If a project manager really wants to set up a local dev env for whatever reason, they can be my guest but don't expect me to tailor our whole everything around them and not my developers.

Re:Mistakes I've Made as an Engineering Manager by Kranar on Sunday February 21, 2021 @07:18PM (#26218813)
I assume you're referring specifically to the coding style document rather than the host of things that a company should document. The advantage of having the coding style documented in a format that supports some kind of markup over a plain text file is to support syntax highlighting, searching/indexing, cross referencing other documents, including diagrams and a host of other features that plain text files lack support for.
Re:Mistakes I've Made as an Engineering Manager by tharkun__ on Sunday February 21, 2021 @08:16PM (#26219424)
You should not assume and I should have specified more clearly.

Our code style is also committed. As spotless configuration files, eslint configuration files etc. You can run these locally if you want to. Our CI/CD definitely runs them and fails the build if it doesn't pass. No exceptions.

The README.md I am speaking of is actually more than one README.md. We have more generalized ones dealing with "This is how to set up your dev env, so you can actually develop stuff", to more module specific ones like "this module is special from everything else in X, Y and Z".

Re:Mistakes I've Made as an Engineering Manager by jskrablin on Monday February 22, 2021 @02:18AM (#26221708)
Documentation that ends up rotting and being ignored is usually a consequence of a poor organization/processes. Such places are usually not a very happy place to work at.

How exactly can you use an email (or email thread) buried somewhere as a part of onboarding process? How exactly can you improve that email when it shows as unclear/lacking info after you somehow managed to use it during onboarding?

Re:Mistakes I've Made as an Engineering Manager by afarrell on Monday February 22, 2021 @04:25AM (#26222430)
Documentation rotting is fine so long as:

1. It is easy to tell which documents are clearly marked as snapshots in time vs. living documents.

2. Most docs are snapshots, so people have enough energy to maintain the living documents.

3. There is a slack channel or team name on the living documents. That way, if you see something out-of-date and want to update it, you know where to ask.

Re:Mistakes I've Made as an Engineering Manager by keithnz on Sunday February 21, 2021 @05:54PM (#26218189)
from years of doing wiki documentation, document rot is fine, if it rots, so be it. Most of the time I write the docs for me but with a "getting started" frame of mind. On our wiki there are a whole bunch of actively maintained pages now that were initially seeded by myself or other devs, and there's a bunch of dead pages which are occasionally very useful , some of it is horribly dead. But the active pages are great, they save everyone time. Main thing is to not invest vast amounts of time to the docs, don't spend time drawing diagrams unless its a photo of a quick hand drawing, and just put in more effort as things prove useful
Re:Mistakes I've Made as an Engineering Manager by ryanSrich on Sunday February 21, 2021 @06:55PM (#26218623)
I think this is all cultural. Smart employees want to do good work. If you aren’t providing them with the context and knowledge to do that work, then you’re failing. If your documentation isn’t useful, that’s your fault. If no one cares about the roadmap and couldn’t even tell you what’s on it, that’s your fault.

It’s very rare you find an employee that’s purposefully malicious, at least in the early stages of a company (< 50 employees). Unless you have terrible character judgement.

If what you are writing down has value, and there’s no other way to obtain that knowledge, then people will use it.

Re:Mistakes I've Made as an Engineering Manager by ska on Sunday February 21, 2021 @06:18PM (#26218356)
> I think most/all documentation ends up rotting and being ignored.

This is a choice, not a fundamental law.

Re:Mistakes I've Made as an Engineering Manager by carbocation on Sunday February 21, 2021 @04:43PM (#26217542)
Not really a general counterpoint, but I do think that if documentation is concise and useful enough so that stakeholders keep it up to date, it can work.

For example, I maintain a document that helps me keep track of bioinformatics files and some of their quirks (which files have two-line headers, etc). I do it for myself, but this information is also referred to by dozens of people in our group.