Conversation

Notices

1. Embed this notice
   Kyle Davis (linux_mclinuxface@fosstodon.org)'s status on Friday, 03-Jan-2025 08:45:52 JST Kyle Davis

   • Jonathan Yu
   • Sandor Szücs

   @sszuecs @jawnsy the docs problem in OSS is nearing a crisis.

   • Embed this notice
     joel b (skotchygut@social.tummyacid.net)'s status on Friday, 03-Jan-2025 08:45:50 JST joel b

     in reply to

     • Jonathan Yu
     • Sandor Szücs

     @linux_mclinuxface @jawnsy @sszuecs the documentation is the actual product. The system you build merely serves the purpose of demonstrating the documentation produces a working system.

   • Embed this notice
     Jonathan Yu (jawnsy@mastodon.social)'s status on Friday, 03-Jan-2025 08:45:51 JST Jonathan Yu

     in reply to

     • Sandor Szücs

     @linux_mclinuxface @sszuecs Do you see docs problems as distinct from OSS sustainability as a whole?

     I think docs are often kinda rough because many projects are driven by volunteers, and writing good docs takes time and skill.

     What are your thoughts?

   • Embed this notice
     Kyle Davis (linux_mclinuxface@fosstodon.org)'s status on Friday, 03-Jan-2025 08:45:51 JST Kyle Davis

     in reply to

     • Jonathan Yu
     • Sandor Szücs

     @jawnsy @sszuecs it’s especially bad in OSS but software in general has a docs problem.

     Overall, I think there is a wholesale undervaluing of those who write docs vs someone who is doing “engineering” (hint: docs _are_ engineering).

     If you’re wanting to go and support your family you are incentivized to be an engineer (higher pay, better career prospects, etc.)

     Yet writing good docs are (IMHO) harder than writing good software.

     Rich Felker repeated this.