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.

#AI #LLMs #documentation #unpopularopinion

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

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.

https://ratfactor.com/b/technical-books

#books #reading #documentation

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.

#interlisp #documentation #lisp #retrocomputing

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

#HelpWanted

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

#HelpWanted

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

https://blog.guillaume-gomez.fr/articles/2020-12-04+doc%28alias%29+is+stable+and+it%27s+gonna+be+super+useful%21

Example:
https://github.com/smol-rs/async-io/pull/242

cc @imperio

#RustLang #UX#A11y#Documentation

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

https://blog.guillaume-gomez.fr/articles/2020-12-04+doc%28alias%29+is+stable+and+it%27s+gonna+be+super+useful%21

Example:
https://github.com/smol-rs/async-io/pull/242

cc @imperio

#RustLang #UX#A11y#Documentation

🚯 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/

#engineering #software #oss #foss #markdown #documentation

🚯 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/

#engineering #software #oss #foss #markdown #documentation

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

https://www.bookstackapp.com/blog/bookstack-release-v25-07/

#Documentation#SelfHosted#OpenSource#KnowledgeManagement

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

https://www.bookstackapp.com/blog/bookstack-release-v25-07/

#Documentation#SelfHosted#OpenSource#KnowledgeManagement

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 :-].

#RustLang #documentation

Today BookStack turns 10 years old! 🎂

In this blog-post we celebrate this decade of BookStack with a Q&A, while also diving into the stats & finances of the project:

https://www.bookstackapp.com/blog/decade-of-bookstack/

#selfhosted #documentation #opensource #php