#Discord is just bad and it doesn't do anything people use it for good at all.
Discord is just bad and everyone who considers using it for anything serious like a #FLOSS project should get forced to reconsider because Discord is ableist garbage and has unacceptable ToS!
📸 Need to backup your Rocky Linux servers? Run -rsnapshot. It works well, is super fast, and keeps a running backup that you can restore from easily. https://docs.rockylinux.org/guides/backup/rsnapshot_backup/ Side note: If you happen to run into any errors in this procedure, let us know so we can improve the docs. #documentation #excellence #rsnapshot #tutorialtuesday #howtoguide
Taking notes and writing detailed docs is my superpower. This article explains why you should too.
> what’s your motivation to create such good docs?
A couple of days ago, a colleague asked me the above question.
That was the 4th person commenting positively within the same week about that specific wiki I wrote, so I decided to write down an article about my thinking.
Read the full article to learn why I love writing detailed documentation: https://www.lambrospetrou.com/articles/writing-docs/
All talks from last week’s #WriteTheDocs conference are now ready to watch online ✨
There’s some super good material here for anyone interested in documentation and tech writing, including:
… oh and yours truly did a talk on AI ethics for tech writers: https://www.youtube.com/watch?v=SDzP6Xs9WoQ
Here’s the full playlist: https://www.youtube.com/watch?v=96V202-7Ovk&list=PLZAeFn6dfHplddJfvbke1bpUzZGozb2Yj
The beauty of writing documentation for code, no matter how tedious, is that it forces you to describe what you built. That can expose various naming issues and hidden mistakes. In my current little project I ended up renaming a bunch of things so the system is more easily extensible and fixed one case where a variable was not named for the actual thing I was putting in it.
Today we released our new digital preservation documentation guide to the world! This was a result of a community collaboration to discuss some of the big questions on the important (and definitely not boring) topic of documentation. Do dive in! #digipres #documentation #ipres2023
[Veille] Digital Nouveau guide la Digital Preservation Coalition ( @dpc_chat
), Digital Preservation Documentation: a guide [Rapport], Digital Preservation Coalition, 2023, doi:10.7207/documentation-23
#digitalpreservation #RDM #guidelines #documentation
We are thrilled to present the recently created Software Heritage #documentation landing page for users and contributors at docs.softwareheritage.org.
On the landing page, you can browse the available resources and also contribute to improving the documentation!
Don't let your friends use GitBook - it's closed source and it's buggy.
I would like to explain to anyone wondering why a commercial no-code WYSIWYG UI proxy frontend for GitHub isn't the way forward for #documentation through examples from GitBook.
But only if anyone has the opposite experience 🤷 Otherwise, I'll just say... trust me, I've used it enough now 😖
Some people may consider writing #documentation to be a lost art, but pruning outdated information from it is clearly not at the top of most to-do lists either. Or, to put it another way, the #wget man page includes instructions on how to export cookies from #Netscape 4.x, the last release of which was issued in October 1998.
On the final #WriteTheDocs day, Fabrizio Ferri-Benedetti describes how they wrote *Amir and the Magical Lens*, a children's book, to explain OpenTelemetry: https://www.splunk.com/en_us/resources/amir-and-the-magical-lens.html
Hello scientists in 🇫🇮 and 🌍 - @coderefinery starts next week, and everyone is invited. This isn't a programming course, but extra tools (#git, #testing, #reproducibility, #documentation, etc) needed for a scientist to do programming comfortably. T-Th, Sep 19-21 and 26-28, online.
Got #LibreOffice 7.6, our new big release? Then also grab the accompanying Writer Guide for it: https://blog.documentfoundation.org/blog/2023/09/12/writer-guide-7-6-is-ready-for-you/ #foss #opensource #documentation
How to avoid leaking sensitive info in your documentation? Final list of recommendations from Kristine Sihto's (@SpliceFixer) talk:
* Sanitise your documents before using them as templates
* Be careful what your showing in screenshots
* Give your clients PDFs rather than Word documents
* Try not to give away too much information in your metadata
* Reduce unnecessary information in version control
* Hide information from people who don't need access to it (= principle of least information)
* Enforce [these principles] through documented processes and extra sets of eyes
Another documentation risk: screenshots! Sihto discusses how some programmes will allow you to crop screenshots ... without actually changing the actual file. What info that you didn't actually want to share, is at the 'hidden' (but revealable) parts of the image?
Talk abstract here: https://www.writethedocs.org/conf/atlantic/2023/speakers/#speaker-kristine-sihto-papercuts-stop-the-bleed-reducing-information-leakage-from-client-bound-docume-kristine-sihto #security #cybersecurity #techwriting #documentation
@daria Simply better explanations.
The docs, like a lot of technical #Wikipedia articles, value accuracy and precision over clarity and understanding.
@GossiTheDog Please tell me if I got something wrong, but in the latest blog article https://msrc.microsoft.com/blog/2023/09/results-of-major-technical-investigations-for-storm-0558-key-acquisition/ there is a #psychological aspect that catches my attention. Though #Microsoft admit that they didn't update the #API library according to their #documentation they introduce this by "To meet growing customer demand to support applications which work with both consumer and enterprise applications [...]".
In my opinion this make #customers believe that requesting a #feature like that leads to #security #threats and it's probably best to have Microsoft fully #control their products and just eat out of the palm of their hand while this situation rather shows that they are not in full control of their systems for other reasons. The responsibility of this incident is not fully undertaking by them. It's kinda your own fault.
#Technical #documentation is too often written by the engineers/etc who built the system being documented. Most of what a normal person first exposed to the system would need to know to make sense of it is so #obvious to them they don't even think about it.
I do my best to try to get into users' headspace when writing docs. But there's something to be said for having a dedicated technical #writer who can be that typical user and document what end users actually need.
🆘 Depuis février 2022, le service Archives et Ressources documentaires de Saint-Nazaire est malheureusement sans responsable...
- on a la mer🌊
- une équipe top 🤝
- des projets à porter et d'autres à inventer💡
Dit, Mastodon, tu ne connaitrais pas quelqu'un qui serait intéressé par tout ça ??
Les repouets sont plus qu'appréciés 👍
@andypiper I've now gone a touch backwards on the "#automate everything" thing often favoured by "10X developers" and management. Similar to reducing dev to dev content I worry that automation can reduce people's [*] understanding of the underlying actions, making people don't have to learn them, and risk running into trouble if it goes wrong and needs to be debugged/changed ... Unless adequate #documentation are in place, which they often aren't
[*] - Except the person who wrote it
Orson was developed as part of my PhD research, and now that I am just working on some Minor Corrections to my thesis, it is no longer a funded project.
That fact, together with a recent trip to the Outer Hebrides has meant that the development rate has been slower of late. I will be starting a new job very soon too, so updates will continue to be less frequent.
However. I will continue to work on it, and treat is as a long-term project, not least because I use it daily myself, but also because it hasn't yet achieved its potential with regards to my research interests. So expect more updates in future!
Most recently I have done considerable work in updating the Orson code base from Vue2 to Vue3 (not published yet) and in getting rid of a lot of duplicated code at the same time.
As Orson is an open-source project I encourage others to get involved, particularly because of the new limits on my time. One of my goals is to improve the plugin system, in order to encourage plugin authorship by contributors.
please write good #documentation. publish it on a static website. ask for help if you need help.
there is a reason good technology comes with good docs, not discord channels.
I've spent a few hours debugging an issue that hopefully no one else will encounter thanks to one word added in the documentation 🤞
(I’m working with a client who has a very old wikiMedia install and is looking to move to something they don’t host.)
This isn’t for external/public use, just to host #guides for staff and other internal things
Any suggestions of what you like is appreciated 💜💜
I applaud #Microsoft for putting their docs on #GitHub and allowing community members to submit PRs to fix these issues, but I can't help thinking that this policy has actually backfired to a certain degree, because it gives the people responsible for writing the #docs in the first place a false sense of security and/or an excuse not to put in their best effort. I think they're too often cutting corners, pushing new #docs into production without a proper #CodeReview, and simply relying on the community to tidy up their messes. Unfortunately, though many of us in the community have the requisite knowledge to fix issues like this, those with the highest levels of knowledge naturally also have the lowest levels of free time for contributing to #OpenSource #documentation, so the issues that are likely to cause the most problems for beginner and intermediate #developers are also the least likely to be corrected by a community-submitted #PR.
Is it just me, or has there been a significant downturn in #Microsoft's #documentation quality over the last year or two? On any given #MSLearn page, I can usually find at least one issue. Some are mostly harmless or mildly irritating (grammatical errors, misspellings, broken links, etc.), but many are worse than that. Vague, missing, misleading, erroneous, or otherwise unhelpful documentation is actively detrimental to the efforts of any developer attempting to write good code, and it's basically impossible to catch this stuff with spelling/grammar checkers, #code linters, etc.
A lot of tools generate or output #SVG. But, oh boy, is it usually bad SVG. Bloated with inline attributes and meaningless order. Bah.
I spent probably 5 hrs life unwinding a SVG generated by drawio into something reasonable enough to add to some #documentation.
What I'd love is some tool could use a heuristic or AI to assign classes and IDs to SVG markup and maybe even group visually connected items together.
I've been tasked with single-sourcing some docs that we should've single-sourced from the start (which I suggested at the time). 3 doc sets, built from 3 different branches of the same GitHub repo. Comparing branches on GH shows 148 & 300 files different between main branch and the other 2. At least some of those files are the same in all 3 branches, so I don't trust that compare tool.
It's nice at least that more people agree with me now, I guess?
Most recently, this was through educating about the JSON format and new #GenerativeAI features.
Does anyone have any favorite blog posts/short articles on writing documentation? Extra points for ones about documenting metadata schemes or writing documentation in a GLAM-context! A lot of what I've found has been too specific to documenting code or it is documenting projects using very basic metadata. #documentation #metadata #libraries #archives #GLAM #DH