That devs in FOSS projects are 1st-class citizens and doc writers are 2nd/3rd has been so pervasive for so long, that I *still* I dismiss my almost 20yrs of writing and only treat my relatively small code as my "real" contribution. Glad to see some communities trying to fix this.

@kyle agreed, what are some communities you have seen that are doing a good job addressing it?

@edsu I don't have specific names in mind (except maybe Jordan Sissel), but what I'm mostly seeing is pockets of discussion within a number of communities, especially when they see someone who submits docs undervalue their own work when they submit it. Other contributors correct that and emphasize the value of docs.

@kyle yes that's a good practice to encourage, thank you for sharing that. I guess including documentation work in change logs could help too. A small thing but taken in aggregate I think it could be helpful.

@kyle one of the discussions I had with my team today was in fact the importance of documentation. It's now a performance target for the year for everyone on my team.

That said, my process for documentation occurs while I'm writing whatever I'm writing. This is, for me, mostly due to the fact I often question my abilities in even languages I use daily. Documenting what I am trying to do helps me accomplish the goal, and avoid perpetual feature creep.

@kyle This is true even in languages that are considered at a higher level of abstraction. i.e., closer to human language or clearer in describing the problem solution. Leon Starr does a very good job of explaining why good documentation is important in his book, Executable UML: How to Build Class Models. He also stresses how important it is to preserve even the little pictures that you might draw to help yourself understand the problem. Documenting assumptions is very important.

Sign in to participate in the conversation
Librem Social

Librem Social is an opt-in public network. Messages are shared under Creative Commons BY-SA 4.0 license terms. Policy.

Stay safe. Please abide by our code of conduct.

(Source code)

image/svg+xml Librem Chat image/svg+xml