Addendum: I was wrong!
Original Post:
@dalias @servo already the #documentation seems to be #AI #hallucinated garbage.
And yes, undocumented, buggy and inefficient code will be the result, even if we don't think IP would be an issue...
@ptrc if one can't be assed to #code and #document themselves, why should I use their #software or trust their #documentation???
We have updated our Python Basics tutorial to describe the guidelines for docstrings in more detail:
https://python-basics-tutorial.readthedocs.io/en/latest/document/sphinx/docstrings.html#guidelines
#Python #Documentation #DX
new & final status update on 'moving image zines rdam':
The complete archive (355 videos) from 2005-2025 has been uploaded & is available on archive.org: https://archive.org/details/moving-image-zines-rdam?sort=-date
All videos are downloadable as high-quality files [mp4/h264 codec, 32 Mbit/s] and reusable under the Creative Commons Attribution-ShareAlike 4.0 International license.
Good #Coding practices question for #Documentation:
Are there some general guidelines on what info to put in the comment at the top of each code file? Like date, author, basic description of what the code does? Maybe something about dependencies? Are there templates for this somewhere (e.g. for #Matlab or #Python if that matters)?
Do you agree? High-quality documentation is essential — especially for feature-rich software like OpenProject.
That’s why we keep our guides up to date in English, German, Spanish, French — and soon Portuguese! — while also investing in video tutorials.
In our latest blog article, we share our approach to great documentation and video content, and introduce Dicle, our new Video Production Manager:
I am working on creating a handbook that describes the assistive technologies available in the FreeBSD operating system, which will be freely available online for anyone to consult. Currently, the effort is focused on gathering and documenting accessibility features for visual impairments, and it is sponsored by the @FreeBSDFoundation
If you are interested in the topic, a public repository is available for suggestions and corrections: https://gitlab.com/alfix/freebsd-accessibility
"The following are my suggestions regarding what else to consider for each of Daryl White’s excellent questions about choosing a toolset for documenting a software product or project.
I have appended a brief guide to the main/broad categories of documentation toolsets and some of the platforms/components that are popular in each.
Finally, this resource ends with a table of possible solutions for various scenarios you might find yourself in.
Before we start with the existing list of questions, I want to highlight one that I think is most important of all, but which is often assumed by people who create these kinds of guides, as they tend to come from one or another world already.
What are you documenting?
When it comes to software technical writing, the more appropriate way to ask this might be: For what user roles is your documentation intended?
For graphical end-user interfaces (GUIs), the largest range of docs tooling is available, but here some of the more commercial turnkey tools have most of their advantages.
For administrator interfaces (installation, configuration, etc), again any tooling will work, but we start seeing real advantages for lightweight markup, codebase integration, and version control.
For developer interfaces, docs-as-code offers significant advantages. Developers can better contribute directly, and it’s generally friendlier for coded samples. APIs (native and remote), SDKs, and CLIs are almost certainly best documented in a docs-as-code environment, even if you integrate it with a more conventional platform for end-user docs."
https://gist.github.com/briandominick/d4cbe11228de0ebe31cda630976af4ef
@lattera every line of code and new algo or what have you can have provenance and confidence rating as well as tell you exactly what is happening - all the metadata, they have the resources to own and they do interdiction and camp out for years #manpage #tldp #documentation #metadata #katie sstam #ft meade
New #Documentation: Automatically Deleting Old Gitlab Issues
Author: Ben Tasker
@AnnieBuddy @mjd @simontatham @fanf +1
Unlike a #Video, I can actually #search a #documentation and unlike a video, I can get a translation either automated or at an acceptable price.
I'm working on some new documentation for phpDocumentor, how is this better than extending @phpdoc so others can benefit from the changes I do.
An extension that can be used to document restructuredtext directives, and improve the way we handle attributes in phpDocumentor.
Hire more technical writers: Isn't the solution obvious?? :-D
"Documentation was especially valuable when it came time to refactor code by providing a blueprint that saved time and improved focus. The researchers found that good documentation “ensures that refactoring efforts are directed towards tangible and specific quality improvements, maximizing the value of each refactoring action and ensuring the long-term maintainability and evolution of the software.”
As our co-founder Joel Spolsky put it, documentation encodes generational wisdom that goes beyond the simple specs of what was built. “Think of the code in your organization like plumbing in a building. If you hire a new superintendent to manage your property, they will know how plumbing works, but they won’t know exactly how YOUR plumbing works,” said Spolsky. “Maybe they used a different kind of pump at their old site. They might understand how the pipes connect, but they won’t know you have to kick the boiler twice on Thursday to prevent a leak from springing over the weekend.”
If we know from decades of research that documentation is a key component of creating and maintaining quality code, why is it so often considered low-priority work developers would rather avoid if they can be writing code instead?
(...)
By embracing AI-powered documentation tools, development teams can significantly reduce toil work, mitigate technical debt, and foster an environment where developers can thrive. Wise organizations will also keep humans in the loop, ensuring that documentation engineers or technical writers act as editors and stewards of any AI-generated documentation, preventing errors or hallucinations from creeping into otherwise accurate docs."
#Documentation #SoftwareDocumentation #TechnicalWriting #SoftwareDevelopment #Programming
https://stackoverflow.blog/2024/12/19/developers-hate-documentation-ai-generated-toil-work/
"[T]he lack of a clear entry path makes the profession less accessible, contributing to a lack of diversity in tech writing teams. If technical writing is to remain relevant in an industry that values innovation and inclusion, it needs to welcome new voices.
Fixing this problem won’t happen overnight, but there are steps companies and the broader industry can take to rebuild the pipeline for entry-level talent:
- Reintroduce mentorship programs.
- Companies can pair senior writers with juniors to share knowledge and help newcomers build confidence.
- Redefine “entry-level” roles.
- Stop asking for years of experience in entry-level job postings. - Focus instead on transferable skills like writing, research, and adaptability.
- Create apprenticeships or internships.
- Paid opportunities to learn on the job can give aspiring writers the experience they need to land full-time roles.
Invest in training.
- Documentation teams should have budgets for upskilling new hires — not just hiring pre-trained professionals."
Documentation: Write it down, save future you
Struggling to remember what your own code does? Imagine how others feel! 
Good #documentation makes your code usable, shareable, and way less frustrating. Let’s make it happen.
Learn how in our workshop: https://coderefinery.github.io/2025-03-25-workshop/
Two hours after doing a talk on documentation and why it's so important, I receive an email that my app, named A4JPHNAJC needs attention.
I guess none of us is perfect all the time
