If you have the stones to try it

What a twist

What if you only have a nail?

I thought it was the other way around and CE was clear entry, C was clear.

Or if they don’t bother to read the instructions they uploaded

The peer reviews are downright diabolical

Must have been the wind

One line best-fits all

Well, it seems Wikipedia was wrong at least about the second half of that sentence

I wonder how the species was discovered

Spared no expense

It says least concern but why am I feeling so concerned

What if the camel had a crush fetish? Has a whole new weight to it.

Users are the acceptance testers.

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.

Saddam has some incredible crush resistance, we should start making entire submarines out of whatever material that is.

Your resume really stood out to us but we’ve heard some disturbing allegations of misconduct regarding your treatment of rocks we wanted to give you the opportunity to address.

It’s a good point but the inverse is also true. Throughout history those in power have needed those below them to work. In cases where those doing the work are mistreated to a bad degree there is always the threat of withdrawing labour but if robots are doing everything, that threat becomes meaningless.

I personally think we would eventually end up in a much better place than we are now if we had full automation of all labour but I agree with the other commenter that it would likely be a painful process. Those who own the robots would have all the power at least initially. If they want to stop those below them from using robots? There are many solutions to that but ultimately if the rich have all the robots then they will effectively also have a monopoly of force too, assuming robots are significantly more combat capable than humans.

Like I said, personally I feel reasonably optimistic that it won’t come to that and we’ll end up in a good place, I just don’t want to downplay the risks too much.