123dev #34: The importance of docs

#34・
47

issues

123dev #34: The importance of docs
By Justin Garrison • Issue #34 • View online

A uniquely shaped puzzle piece slides into place in a finished puzzle
A uniquely shaped puzzle piece slides into place in a finished puzzle
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
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
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.
Did you enjoy this issue?
Justin Garrison

1 gif, 2 comments, and 3 links to make you a better developer and person

In order to unsubscribe, click here.
If you were forwarded this newsletter and you like it, you can subscribe here.
Powered by Revue
Los Angeles, CA