Hmmmm, I locked an open door…

No worries, sounds like you’re definitely on the right track with your approach.

In terms of the style of editor I don’t have a strong preference, I think the most important thing is discoverability which generally means putting docs where they are expected to be found and using whatever your team or org is using. Personally I have a slight preference for markdown mainly because it’s easy to version control, see who wrote what (so I can ask them questions) and use all the tools I’m used to that work well with plain text. Tools that use more WYSIWYG style can be good too though and many of them like Notion have the advantage of making it relatively easy to search across your entire companies documentation assuming everyone uses the one tool.

For my personal notes I use Logseq which I highly recommend. It’s a bit of both, markdown under the hood but with a simple editor that lets you focus on writing notes, tasks and links.

I would say as a new junior dev you are uniquely placed to help with this. Documentation tends to be written by people who know a lot about a thing and they try to imagine what might be useful for someone. Someone new coming in with a fresh perspective can help uncover assumed knowledge or missing leaps to make the documentation better. One of the common onboarding steps I’ve seen is to go back and update/improve the onboarding docs after you’ve just been onboarded for example.

I would say pick your battles though because documentation can be a never ending task and documents are almost always out of date shortly after they are written. Think about what would have saved you time or mental overhead if it was just written down and fix those first.

As far as organising and writing, every place is different and it can depend on the tools your org is using. In general I’d at least have links to relevant docs as close to where they might be needed as possible. Like how to set up and get up and running with a code base should probably be documented directly in the readme, or at least linked to if it’s overly complicated.

Hopefully that’s at least somewhat helpful. It’s definitely a problem basically everywhere I have worked though, you have to do what you can and not stress too much about it.

My name is Connor, I’m the android sent by Cyberlife

I dunno, it’s already pretty good at writing code and only going to get better. I agree with your conclusion though, mainly because as a software engineer writing code is actually not even the most complicated part of the job. If an AI could write perfect code every time it’d make my job a lot easier but I’d still have to do a significant amount of work such as:

• Figuring out which code to write in the first place! Work discovery if I’m senior enough or clarifying requirements.
• Co-ordination with other teams. Depending on the exact work this becomes more or less important
• Managing the lifecycle of a change including testing, deployment, monitoring and triaging issues.
• Ongoing maintenance. Staying on top of upcoming changes in adjacent or foundational teams, making sure our stuff will keep in working.
• Architecture design. You mentioned this in your post, understanding interactions with adjacent systems and how to organise our own systems to meet current and (reasonable) future requirements.
• Conducting non project work such as interviews, involvement in working groups to help decide overall technical direction of my group, upskilling myself and those around me.

That’s just off the top of my head, I’m sure I’ve missed some things. As much as I love writing code I honestly feel like if an AI could do that part it’d just take stress out of my day and give me more time to focus on those other parts of the job. Of course in reality more work would probably just be piled on but that’s just life I guess.

Impossible, no plate can slay me!

That is no plate 🥣

Cast your eye on this you glorified lighthouse.

Oh no I see the misunderstanding here, it should be

Resist, tomorrow!

I’m going back to bed now

Just don’t lie to the engineer about your weight

No wrong times, only small periods of unfortunate times!

Thanks so much for the explanation. As they say, when a measure becomes a target it stops being a good measure.

Relevant XKCD for good measure.

How can these businesses keep running? Storing and distributing documents isn’t exactly the most technically challenging product to build. I’m not in the field though so I’m absolutely certain I’m missing a lot of the nuances here. Can you shed some light on why you think nobody new comes along to our compete these folks?

In video form

Careful, Windows can be vomit inducing.

Truly a paradise, except when it isn’t

I was thinking Linux at home would be Windows Subsystem for Linux.

Frodo: … well I’m more into writing so … I guess as long as I can keep all my fingers I’ll do it.

Gandalf: yeah yeah cool don’t worry about it you’ll definitely get there with all your fingers

Oh God, this brought back a traumatic memory. I was hanging out after hours at our office to look after a meetup group that was using our space that night. Nothing tricky, make sure people can get in, keep the lights on, make sure nobody sets the place on fire.

I was plugging away on my personal laptop which had Linux on it. Having a great time doing something or other when one of the meetup organisers approached me with a USB stick and asked if I could help them print out some signs to help people know where to go.

My install was rock solid, fast and set up exactly the way I wanted, but in that moment none of that mattered because it was me who froze. I thought back to all the decisions that lead me to that situation, even the conversation with a coworker a few months ago about Linux who literally said “I love Linux but one day I’m just afraid I’ll have to print something or whatever and I won’t be able to”. How foolish I was to dismiss the wisdom in his words that day, and now my worst nightmare had come to pass.

I swallowed hard, looked the organiser in the eyes, and told them I couldn’t help them. I didn’t even try. Best to rip the band-aid off, disappoint them now and get it over with. After the glaring admission left my mouth I waited for the inevitable response. I was a fraud, nothing more than a self proclaimed computer geek who couldn’t accomplish a rudimentary task despite all my time studying and tinkering. It was over, I guess it wasn’t imposter syndrome after all, I really was an imposter and now I’d been discovered.

But instead the the organiser just smiled and said “that’s totally ok, we were just a bit disorganised and didn’t print it before coming this time. Thanks for your help anyway!” And everything was fine. This time.

Where we’re going, we don’t need graphite to draw

Fold, you fools