4 ms·
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 thin
by TheOtherHobbes 4y ago
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 ref manual typically has a list of all moving parts but often lacks a list of concepts and terminology. So you look up $thing and have no idea how it fits into what you're attempting to do.
A series of mid-level task-based examples ("How do I...") for the most common use cases goes a long way to bridging that gap.
Also list any platform specific quirks. (Not just "To install this use homebrew $name for MacOS and apt-get $name for Ubuntu.")
And run a forum where people ask questions. Collect the most common questions into a literal FAQ and/or include them in examples/reference.
Never say "That's in the manual." Especially not when the manual is 1000 pages long and gives a two sentence description of every feature with no use cases.
- ilyt 4y agoI 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)
- wbeckler 4y agoThere's a framework to do this in most major languages. I think python started this with TestDoc.
- jalino23 4y agothis makes sense I’m guessing this is why I love go and rust so much. it’s like I have the confidence to just figure things out when I get stuck cause of the docs it has
- rr888 4y agoTDD in theory sounds great. What I've seen is thousands and thousands of tests, inconsistently written by dozens of different developers over the years. Testing silly little trivial things that makes the CI pipeline 10+ minutes. A least if you have lots of obsolete difficult to read docs you can easily ignore them, tests however are particularly toxic as it makes refactoring and cleanup very difficult.
- pif 4y ago> tests however are particularly toxic as it makes refactoring and cleanup very difficult. Properly written tests check the interface contract, and thus are very friendly watchdog that will warn you as soon as you got out the right path. Tests that check the implementation details, instead, are hardly ever justifiable.
- mhuffman 4y ago>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.
- solarkraft 4y agoI think that's the type of software I'd at best use reluctantly and complain about.
- mhuffman 4y agoWell this is usually what people do. It usually is some company that has a dated or not great app, but has sector capture because they were first or were wise enough to spend on sales and marketing. After that, bigger (non-tech) businesses and governments, just "stick with what works" no matter the aggravation.