5 ms·
> Technical writers: documentation by example is good only for newbies skimming through. People familiar with your product need a reference and exhaustive lists
by johanbcn 2y ago
> Technical writers: documentation by example is good only for newbies skimming through. People familiar with your product need a reference and exhaustive lists, not explanation for different fields spread over 10 tutorial pages. Focus on those that use the product day in and day out, not solely on the "onboarding" procedure.
I agree. We all would benefit by giving more exposure to documentation frameworks such as https://diataxis.fr https://diataxis.fr
- yread 2y agoMSDN also follows these principles
- adolph 2y agoI'm glad to have clicked through for curiosity's sake. Diátaxis is tremendously interesting. For folks who might recognize the author's name: Daniele Procida: Director of Engineering at Canonical. Creator of Diátaxis and BrachioGraph. Django core developer. Fellow of the Python Software Foundation.
- yoyojojofosho 2y agoDiscussed on HN: https://news.ycombinator.com/item?id=33721314 https://news.ycombinator.com/item?id=33721314
- siamese_puff 2y agoAlso https://docs.divio.com/documentation-system/ https://docs.divio.com/documentation-system/
- FelipeCortez 2y agoThese are "the same". Diátaxis is the fork the author made after (I presume) they left Divio.
- siamese_puff 2y agoAh TIL
- deleted 2y ago[deleted]
- molszanski 2y agoThank you for the link <3