Rakhim emphasizes the importance of examples in software documentation.
https://rakhim.exotext.com/examples-are-the-best-documentation
Jeremy ⁂
boosted
Serious question for those using #AI to write code comments and code #documentation :
Isn't the kind of documentation it generates trivial?
I mean: if you are just describing what a method or class do, I can read that on the (clean) code myself. I don't need that repeated.
What I am interested in is the parts I can't infer from a quick read of the code. Why this decision was made. Why this method looks weird. Why this class hierarchy. Why this code that seems useless can't be deleted.
Serious question for those using #AI to write code comments and code #documentation :
Isn't the kind of documentation it generates trivial?
I mean: if you are just describing what a method or class do, I can read that on the (clean) code myself. I don't need that repeated.
What I am interested in is the parts I can't infer from a quick read of the code. Why this decision was made. Why this method looks weird. Why this class hierarchy. Why this code that seems useless can't be deleted.
I'm all against irresponsible uses of LLMs, but users probably wouldn't turn to a natural language prompt to get a properly understandable doc if the documentation effort was decent enough upstream.
Documentation is hard and boring most of the time, but it's what makes your product usable. Bad doc is plain gatekeeping.
Ambraven :verifinking:
boosted
PAR AILLEURS les mastobébou-tes, si vous avez des tuyaux pour:
- un taf en médiathèque, en archive, documentation, qqc avec des bouquins, de la culture
- que ça recherche temps partiel
- dans les alentours de Nantes ou dans le Pays de Retz / Sud Loire
- et la cerise sur le gateau, si c'est en service public (j'accepte en privé mais j'y suis bcp plus frileuse, politiquement)
Faites moi signe 🙏
C'est pas la motivation qui manque, mais les offres
#emploi #autisme #tdah #chomage #livre #bibliotheque #documentation #servicepublic
PAR AILLEURS les mastobébou-tes, si vous avez des tuyaux pour:
- un taf en médiathèque, en archive, documentation, qqc avec des bouquins, de la culture
- que ça recherche temps partiel
- dans les alentours de Nantes ou dans le Pays de Retz / Sud Loire
- et la cerise sur le gateau, si c'est en service public (j'accepte en privé mais j'y suis bcp plus frileuse, politiquement)
Faites moi signe 🙏
C'est pas la motivation qui manque, mais les offres
#emploi #autisme #tdah #chomage #livre #bibliotheque #documentation #servicepublic
Neil Brown
boosted
We recently created example.ac.uk to follow the same semantics as example.com but in the UK academic namespace. It's now reserved and available for anyone to use in documentation.
#highereducation #acuk #documentation #examplehttps://example.ac.uk
Dave Gauer @ratfactor explains why he reads technical books. He expresses very well motivations I share but couldn't articulate, such as books having a single voice and stylistic convention.
Using LLMs to chat with books and documents? That's so 1978.
In the 1970s the HELPSYS facility of Interlisp-10 let you interrogate the 700+ pages Interlisp Reference Manual via an English like syntax. You could run queries on topics and system functions such as TELL ME ABOUT EVAL or TELL ME ABOUT THE 2ND ARG OF CHANGEPROP and HELPSYS would print the relevant information or section of the manual. Here's an example session from the 1978 edition of the manual:
https://www.softwarepreservation.org/projects/LISP/interlisp/Interlisp-Oct_1978.pdf#page=474
Interlisp-10 was the Interlisp implementation for the PDP-10.
just small circles 🕊
and 2 others
boosted
Is anyone using our #WriteFreely Docker image in production? If so, we could use your help with updating our #documentation!
Let me know if you want to contribute, or just feel free to submit a pull request!
https://github.com/writefreely/documentation/blob/main/admin/docker.md
Is anyone using our #WriteFreely Docker image in production? If so, we could use your help with updating our #documentation!
Let me know if you want to contribute, or just feel free to submit a pull request!
https://github.com/writefreely/documentation/blob/main/admin/docker.md
alcinnz
boosted
Doc aliases are such an underrated feature in #Rust docs! Please use it. 🙏
Doc aliases:
https://blog.rust-lang.org/2020/11/19/Rust-1.48/#adding-search-aliases
Example:
https://github.com/smol-rs/async-io/pull/242
cc @imperio
Doc aliases are such an underrated feature in #Rust docs! Please use it. 🙏
Doc aliases:
https://blog.rust-lang.org/2020/11/19/Rust-1.48/#adding-search-aliases
Example:
https://github.com/smol-rs/async-io/pull/242
cc @imperio
Stefano Marinelli
boosted
🚯 No More Markdown 🚯
Well, it's certainly not going away any time soon, but it doesn't have to be the default. While it's easily a majority of the docs formats that I have to use, it's not my favorite.
Perhaps in an ideal world it would be AsciiDoc or LaTeX All The Time, but we don't live in that world, oh well 💋
In the interim, here's someone who wrote about the topic which seems worth sharing. Interesting points, ja?
- Why You Shouldn’t Use “Markdown” for Documentation: https://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/
🚯 No More Markdown 🚯
Well, it's certainly not going away any time soon, but it doesn't have to be the default. While it's easily a majority of the docs formats that I have to use, it's not my favorite.
Perhaps in an ideal world it would be AsciiDoc or LaTeX All The Time, but we don't live in that world, oh well 💋
In the interim, here's someone who wrote about the topic which seems worth sharing. Interesting points, ja?
- Why You Shouldn’t Use “Markdown” for Documentation: https://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/
Luc, framage
boosted
BookStack v25.07 is now here with a bundle of improvements:
📝 Markdown Plaintext Input Option
✏️ New Comment/Description Editor
🔧 New WYSIWYG Editor Improvements
📋 Improved Changelog Input
📦 ZIP Import/Export API Endpoints
🏷️ Parent Tag Classes
📱 Multi-Column Layout Refinements
🔐 Better Permission Generation
🌍 Nepali Language & Updates
BookStack v25.07 is now here with a bundle of improvements:
📝 Markdown Plaintext Input Option
✏️ New Comment/Description Editor
🔧 New WYSIWYG Editor Improvements
📋 Improved Changelog Input
📦 ZIP Import/Export API Endpoints
🏷️ Parent Tag Classes
📱 Multi-Column Layout Refinements
🔐 Better Permission Generation
🌍 Nepali Language & Updates
alcinnz
boosted
Your regular reminder to use rustup doc to browse the standard API locally, or cargo doc to browse the documentation of your project and its dependencies.
Save network. Save energy :-].