I think the problem is that devs write docs the way they understand it. It's like giving someone giving you their class notes, but they write in short-hand or in analogies you don't exactly understand.
I absolutely appreciate the tag #explainlikeimfive--because, personally, need things to be explained in the most basic, layman terms as possible.
Sometimes people don't want to debase themselves to that of a child, mostly due to pride (and selfishness).
There are some designers (like me) who want to understand how to code better so that we can collaborate with engineers to streamline building a functional and new user-friendly product.
I have yet to find a #nicedoc. :(
Thank you for writing this post! It was a great read!
I think the problem is that devs write docs the way they understand it.
Totally! Thanks for pointing that out. Writing documentation requires a shift in perspective and some detachment from the internal implementation of the code. Even the documentation links I included I think all suffer from this issue.
I wish developers would be more open to inviting other people into the documentation process. The best documentation can only be written by involving people that don't have an intimate familiarity with the codebase. Ideally the terminology used in the code itself reflects the way users actually talk about the concepts involved.
I think the problem is that devs write docs the way they understand it. It's like giving someone giving you their class notes, but they write in short-hand or in analogies you don't exactly understand.
I absolutely appreciate the tag #explainlikeimfive--because, personally, need things to be explained in the most basic, layman terms as possible.
Sometimes people don't want to debase themselves to that of a child, mostly due to pride (and selfishness).
There are some designers (like me) who want to understand how to code better so that we can collaborate with engineers to streamline building a functional and new user-friendly product.
I have yet to find a #nicedoc. :(
Thank you for writing this post! It was a great read!
Totally! Thanks for pointing that out. Writing documentation requires a shift in perspective and some detachment from the internal implementation of the code. Even the documentation links I included I think all suffer from this issue.
I wish developers would be more open to inviting other people into the documentation process. The best documentation can only be written by involving people that don't have an intimate familiarity with the codebase. Ideally the terminology used in the code itself reflects the way users actually talk about the concepts involved.
I hope you find a #nicedoc some day!
You just gave me a brilliant idea. Brb brainstorming.
Excited to see what you come up with :)