3 ms·
Good thought, but > I figure that if you have knowledge that could benefit thousands of people, and it costs you next to nothing to share that knowledge, it’s
by avg_dev 3y ago
Good thought, but
> I figure that if you have knowledge that could benefit thousands of people, and it costs you next to nothing to share that knowledge, it’s your duty to do it.
As someone who has written a lot of docs over the years, there can often be a very high cost in terms of time and effort to document something.
- vitiral 3y agoAlso, there is cost to you to maintain docs and a cost to others if you don't. Some things are near universal and always useful. Documenting by creating a full working example with minimal dependencies will stand the test of time. I'm not saying don't document. Even a list of notes, clearly marked as such, can be helpful.
- lo_zamoyski 3y agoIndeed. To elaborate... 1) Documenting things does cost, especially time. Writing good, clear, cohesive documentation is even more costly. Bad documentation can be costly by consuming the reader's time beyond what is justified. 2) Documentation often needs to be updated and therefore maintained. This is costly. 3) Failure to maintain documentation can leads to even bigger costs because of the confusion and misunderstanding outdated documentation can introduce. 4) At companies, culture is not necessarily supportive of documentation because of the immediate cost of documenting and maintaining docs. You can very well be punished for documenting things, and in doing so, may sacrifice meeting more important objectives. Even documenting things helps others in the company, if the company punishes you for it (and while perhaps rewarding others who profit from your docs), you're not being a hero or a martyr, feelings of moral superiority notwithstanding. You're being a fool. You're not doing charitable work at a company, after all. 5) "Duty" is a strong word. There is no general duty to document things. You can't just assert a duty exists by fiat, without establishing a basis for that duty. There are plenty of good things we can do, but are not duties.
- nicbou 3y agoAuthor here. Tell me about it! I'm documenting things for a living. There aren't enough hours in the day to write everything down. However, I wrote this post while thinking about easy fixes that are really hard to discover, such as this one yesterday: https://nicolasbouliane.com/blog/playwright-timeouts https://nicolasbouliane.com/blog/playwright-timeouts
- giancarlostoro 3y agoEspecially as what you've documented becomes obsolete over time.
- pjc50 3y agoThe worst cost of documentation is that it often generates extra work for you in terms of complaints and updates. Not always reasonable ones, either. More than a few personal projects have been taken offline because it's too demoralizing to give things away and get negativity back.
- nicbou 3y agoI offer them a refund. It gets the point across.
- avgcorrection 3y agoConsidering that some blog post about something can remain relevant for years—as opposed to some off-hand tip given verbally—, it is definitely difficult to just share knowledge in a way that cost you next to nothing. You could give some great advice that works now. But doesn’t in two years. And then it might be counter-productive.
- paxys 3y agoExactly. If it was truly zero cost then everyone would be doing it. In reality concisely describing a complex system is more difficult than building one.
- judemelancon 3y agoDocumentation absolutely has a cost, but that last sentence is a substantial overgeneralization. Counterexamples include a search engine, a quilt, an impact driver, and a box of a basic LEGO bricks.