Writing docs well: why should a software engineer care?

Post by wbeckler » Fri, Nov 25, 2022, 3:13 PM UTC

ilyt wrote: post #25

TheOtherHobbes wrote: post #21

Whether it's FOSS or corporate, people won't use your stuff if it's not documented properly. At best they'll use it reluctantly and complain about it. One thing there isn't enough of is task-driven documentation. Typically there's a getting started guide and a reference manual, with a huge gap between the two. The getting started project is usually at the hello world level - ok as far it goes, which is not far. The r…

I do despise how little there is of examples in most of the docs. Go had a right idea of integrating example code into tests so not only there is one way to add example code, it is also guaranteed to be runnable. It also have side effect of forcing developer to use their own interface they gave to users so they might notice it is shit before people start to complain (or leave defeated and search for different lib)

Post by solarkraft » Fri, Nov 25, 2022, 4:18 PM UTC

mhuffman wrote: post #39

TheOtherHobbes wrote: post #21

Whether it's FOSS or corporate, people won't use your stuff if it's not documented properly. At best they'll use it reluctantly and complain about it. One thing there isn't enough of is task-driven documentation. Typically there's a getting started guide and a reference manual, with a huge gap between the two. The getting started project is usually at the hello world level - ok as far it goes, which is not far. The r…

>Whether it's FOSS or corporate, people won't use your stuff if it's not documented properly. At best they'll use it reluctantly and complain about it. Maybe FOSS, but there is plenty of corporate SaaS and desktop apps that have basically zero documentation and you are told to contact the "support team" if you can't figure something out.

Post by mhuffman » Sat, Nov 26, 2022, 6:33 PM UTC

solarkraft wrote: post #43

mhuffman wrote: post #39

Earlier quoted context omitted.

>Whether it's FOSS or corporate, people won't use your stuff if it's not documented properly. At best they'll use it reluctantly and complain about it. Maybe FOSS, but there is plenty of corporate SaaS and desktop apps that have basically zero documentation and you are told to contact the "support team" if you can't figure something out.

I think that's the type of software I'd at best use reluctantly and complain about.