See article
- The problem is that developers are too close to their product.
- Developers just can't have the viewpoint that's needed for good documentation
- content that is written from the user's perspective
- takes the user’s point of view
- strips away inadvertent assumptions a developer can make
- A big shift needs to occur when writing usable content.
- A developer’s viewpoint when writing documentation is “this is my product; here’s how to use its features”.
- A technical writer, however, creates content thinking “hello user, here is how you’ll be doing the things you want to do with this product.”
- So it’s not the person that is at fault; it’s the role.
See article
- the devs aren't thinking outside of themselves, and thus aren't explaining things clearly enough to the readers.
- they are in a position where they understand what's going on and take for granted the need to explain things as clearly as possible
- Many developers do not feel the need to write documentation.
- When insisted to do so, these developers write horrible documentation as they are simply not interested in the task.
- The result? Unhappy developers with terrible documentation that only they can understand.
- Developers understand what they are working on and that is why they choose to skip the documentation.
- Sounds reasonable, right?
- However, the same developers might forget the intricacies of their own work when they visit it after few weeks, months, or years.
- Writing is not an easy task; it requires critical thinking, patience, and effort.
- For developers, documentation can be a chore.
- According to many, it is just a waste of time and effort as they already know that it requires significant time to produce good documentation.
- Developers prefer to use this time and effort in implementing new features, solving problems, or squashing bugs.
- There is always a due date hanging around the corner.
- The developer needs to deliver the project on time, and no one cares about the documentation.
- The company wants to deliver the project as soon as possible, and the first thing that goes out is documentation.
- The only exception is when the client explicitly mentions the need for documentation.
- Sometimes the reason is pure laziness.
- It's those programmers who are simply motivated by paychecks who are the biggest culprits of not engaging in these activities that don’t yield them more money.
- Programmming requires logical and spatial reasoning—traits that are often more mathematical than anything else.
- Writing, on the other hand, requires some similar traits, but they manifest quite differently.
- Agile is fast, unforgiving, and doesn’t encourage documentation.
- The reason is simple: the code changes too frequently to be documented and hence leads to either poor documentation or no documentation!
- Hubris can lead many developers to believe in not commenting or documenting their work.
- Many programmers opt not to write documentation at all to show their skills and deny their responsibilities for others to understand their code.
- Many developers who are capable of writing documentation don’t do it because they feel they are not good at it.
- They think negatively:
- My writing's not good enough.
- My English is poor.
- I hate writing.
- It's not my job.
- Nobody reads the docs.
- Writing docs isn't as important as writing code.
- I'm busy.
- If they are thinking like this, then of course they'll have trouble writing.
Video documentation
- The developer records his work, only to be explored by other team members or a potential technical writer that works on the project documentation.
- It requires no extra effort from the developer.
- All the stages of development can be stored in video and accessed whenever needed.
- The good thing is that new team members can quickly pick up the project with recorded video cues and proper help from other team members.
Video Documentation Benefits in a Nutshell
- Removes the need for proper written documentation for internal team.
- Provides an excellent opportunity for agile teams to keep track of the changes.
- Helps technical writers to understand better.
- Saves effort and time for developers, enabling them to divert their energies toward writing better code and implementing features.
- Can be used to understand workflow mistakes of team members and improve productivity and efficiency.
See an example here
See video.
TODO
- make documents easily searchable
- use https://www.bookstackapp.com/
See video.
TODO
- record the development sessions we do for each task
- record Q&A sessions where we explain some feature to a new employee
- upload videos on GDrive and organize them in categories