The importance of docs - 123dev #34

Posted on October 9, 2021  •  4 minutes  • 764 words

Comments

Puzzling

Growing up my dad loved puzzles. He had the weirdest rule that I never understood.

No matter how many pieces the puzzle had, he would look at the picture once when he opened it and never looked at it again. Thankfully, he never enforced that rule on us as kids, but I still don’t understand why he did it.

Learning a new framework or architecture is like doing a puzzle. At first you just need to flip all the pieces the right way to understand what you’re dealing with. Then you’ll likely find the edges of the technology to see where things fit. At first putting parts together is slow, but as you get more familiar with the colors and shapes and as more and more of the puzzle is filled you can solve the whole picture faster.

Documentation is the picture on the box. Some puzzles you don’t need to look at the picture and some people like to do it the hard way. But a puzzle without a picture is a special kind of torture.

Where to put docs

With many open source projects docs live in a folder with the code. It makes it easy for developers to update functionality and documentation in a single commit. As the project grows sometimes docs get split out into a separate repo for a multitude of reasons.

I’ve realized how much I like keeping docs with code for as long as possible. Not only are cross referencing code and docs easier—especially as things change—but tests and deployment pipelines can and should fail if documentation builds fail.

Something I never thought of before is keeping docs and app code together also gives adequate credit to documentation writers. You can look at the code history and see who has the most commits, but if docs are in a separate repo the writers are never seen as part of the project or praised for their contributions. The truth is, docs are a critical part of the project and, depending on the project goals, should be prioritized equally with any other project deliverable.

Links

I was never a strong writer in school and I mostly hated doing it. Somewhere early in my career I learned I enjoyed writing technical articles, and it has opened more doors for me than I can count. Now I treat documentation as human automation.

Just like a script can help you automate a repetitive task, or a unit test can validate your code. Your docs are automation for teaching people and scaling yourself. You don’t have to spend time with each new users or answer the same questions 100 times. The best part is you don’t even have to remember the answer yourself!

Spend some time to learn to write. Bad code with good docs scales more than good code with bad docs.

How writing can advance your career as a developer - Stack Overflow Blog — stackoverflow.blog “In their first few years on the job, engineers spend roughly 30% of their workday writing, while engineers in middle management write for 50% to 70% of their day; those in senior management reportedly spend over 70% and as much as 95% of their day writing.” - Jon Leydens

I learned about the web share API this week. It could be very useful once full OS and browser support comes around. For now it can help make websites on mobile feel more native because you get the OS share controls and targets without needing to take up a ton of screen real estate for share buttons.

The Web Share API ← Alligator.io — alligator.io Learn how to use the Web Share API for a simple way to integrate your device’s native sharing capabilities into your website or web app.

This started out very basic with information on how website passwords work (e.g. hashing and salting). It got deep into one time codes and HMAC pretty quick with good code examples. I didn’t realize it was a 3 part series which all had good information if you’ve ever wondered how one time passwords work.

How does Google Authenticator work? (Part 1) When you’re accessing services over the WEB – let’s pick GMail as an example – couple of things have to happen upfront: The server you’re connecting to (GMail in our example) has to get to know who you are. Only after getting to know who you are it’s able to decide what resources you are allowed to access (e.g. your own email inbox, your Calendar, Drive etc.). Step 1 above is called authentication.