#documentation
@dis EXACTLY!
#Discord is just bad and it doesn't do anything people use it for good at all.
It doesn't replace a #public & #accessible #documentation nor does it work good as #messenger or #chat nor does it work for #calling and #ConverenceCalling...
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!
@SwiftOnSecurity EXACTLY!
I'm shocked at the #TechIlliteracy of post-millenial #Kids despite them having easier access to #Documentation and #HowTos than I could've ever dreamed of, despite having #ISDN in 1999...
📸 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
By adding the site goal to our Maven build command, we can generate basic reports about the Java project based upon the pom.xml configuration. #MavenBuild #java #report #site #documentation
http://codingchica.com/2023/09/25/project-reports-generating-a-simple-maven-site-in-the-build/
¿sabían que si subes documentos en Google drivers y si son públicos pueden verlos todos? Acá hay un buscador para encontrar esos archivos de Google driver. Está interesante
https://derechodelared.com/dedigger-buscardor-google-drive/
#google #driver #internet #documentation #documentos #buscador
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/
What is the good way to generate docs in #sphinx for #puppet classes?
#OpenSource #documentation
Please boost for more reach.
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:
* OpenTelemetry explained in a graphic novel, by @remoquete
* Sensitive info you might leak via your documentation, by @SpliceFixer
* OpenAPI for the brave and true, by @lornajane
… 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
#TechWriting #TechnicalWriting #Docs #Documentation #OpenAPI #security #OpenTelemetry
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.
It's so valuable to receive feedback from your users.
Someone recently bought a license of GeniePy and sent in an email with the suggestion to add more documentation to the codebase.
So that's what the next release will focus on! Documentation! 📄
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
https://www.dpconline.org/digipres/implement-digipres/digital-preservation-documentation-guide
[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
https://dpconline.org/digipres/implement-digipres/digital-preservation-documentation-guide
#digitalpreservation #RDM #guidelines #documentation
#SoftwareHeritage #Documentation #LandingPage #sphinx #pydata-theme
- https://www.softwareheritage.org/2023/09/08/swh-documentation-update/
- https://docs.softwareheritage.org/ (#sphinx #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!
#tech #documentation #metaphysics #time
i like it when the documentation gets metaphysical: "there are limitations to nature and physics that will never allow two measurements of physical time to align precisely."
live in the moment, friends!
Doxide v0.2.3 now out, with support for unicode characters in identifiers (for all your mathematics needs) and better Markdown link generation. https://doxide.org #opensource #release #documentation #cpp #cplusplus
You can migrate your systems to Rocky Linux from CentOS, CentOS Stream, RHEL, AlmaLinux, or Oracle Linux, using this handy tool called migrate2rocky. https://docs.rockylinux.org/guides/migrate2rocky/ #documentation #migrate2rocky #tutorialtuesday #howtoguide
Why is the manual of apt incomplete? #commandline #apt #documentation
quick and easy way to build a website for your r package: https://pkgdown.r-lib.org/ #rstats #package #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 😖
Warms my heart to hear Nada Jašíková emphasise the importance of writing #documentation in the You Build It You Run It panel discussion at #PyConCZ23.
We need to really consider documentation as part of building features and fix bugs, not as an extra that is done if you feel like it.
"Future you will love you for adding comments to your code and think past you was much smarter than future you is now... err... then."
Conjugation: the first casualty of time travel...
You know, I always tell people to read the manual whenever they interact with a product and I'm having some serious 🤯 right now reading the #Godot manual.
Like peanut butter and chocolate, someone managed to blend #python and #kubernetes kubectl
:https://docs.kr8s.org/en/latest/index.html#object-api
maybe other #DevOps geeks will enjoy this. It also has well automation #documentation , for anyone who wants to see an example of a good #sphinx project.
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.
#IHSA #policy #update #requires #transgender #athletes to #ask for #permission to #play.
The #Highschool #Association
will seek to review #medical and #school #registration #records, among other supporting #documentation to determine #eligibility.
#Women #Transgender #LGBTQ #LGBTQIA #Education #Sports #SexDiscrimination #Hate #Bigotry #Discrimination #Transphobia
Man I didn't even notice #Flathub now has a dedicated page for its #docs. So much better than the old READMEs on GitHub style! https://docs.flathub.org/
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
Just added a few more basic examples of route parameter usage in Kitten to the routing sample app:
https://codeberg.org/kitten/app/src/branch/main/examples/routing
#Kitten #SmallWeb #routing #web #dev #documentation #examples
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.
https://coderefinery.github.io/2023-09-19-workshop/
If you're at Aalto, invite us to your research group to help put these tools into practice - we don't teach and leave you alone!
#teaching #course #RSEng #OpenScience #HPC
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?
Discusses a security risk of templates: templating an original document, without thoroughly cleaning it up first (removing all client-specific information) -- you may leak sensitive info #documentation #writethedocs
Super interesting talk by @SpliceFixer on preventing information leakage from documentation just kicked off at #WriteTheDocs
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.
I only ever use the #python #documentation to look up specific facts, like constants or string format codes. If I need to *understand* something I look for a tutorial elsewhere.
The docs, like a lot of technical #Wikipedia articles, value accuracy and precision over clarity and understanding.
First make me understand the mental model. Then tweak the specifics. Don't start with the details. #pedagogy #learning
@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.
Indeed.
#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.
And people say open-source software is unapproachable and difficult for the average user!
(Yes, expecting them to write Lisp-like code is "simple" according to the Gnu IMP documentation...)
#OpenSource #FreeSoftware #GIMP #documentation #UI #easy #simple #lisp #scheme #BatchMode
🆘 Depuis février 2022, le service Archives et Ressources documentaires de Saint-Nazaire est malheureusement sans responsable...
Pourtant :
- 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 👍
#archives #documentation #histoire #histoireouvriers #défi #SaintNazaire #patrimoine
@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
I'm doing a bit of (very non-academic) research for a blog post about technical documentation.
Help me out fediverse and reply with your favorite docs and why you like them! Boosts are appreciated.
#documentation #docs #opensource #development #software #webdev #foss
Orson update
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.
#orson
#research
#notebook
#documentation
#digitalhumanities
#knowledge
#vue
#javascript
#opensource
#software
#Development #Guidelines
Please take full window screenshots · Best practices for capturing screenshots in product documentation https://ilo.im/150o8g
_____
#WebDesign #WebDev #Frontend #Browser #DevTools #Documentation #Context #Screenshot
@chipx86 @federicomena You can also drop a markup language that is frozen in the 00s and keeps confusing everyone and switch to MyST, a reST-compatible CommonMark dialect.
You can see a live converter in https://astrojuanlu.github.io/mystyc/, follow @mystmarkdown, and read the docs in https://myst-parser.readthedocs.io/
you have an interesting #hardware or #software #project?
please dont ask me to sign up to your #discord or #telegram or such.
i won't.
i shouldn't have to.
i don't have time to hang around one channel per piece of tech in my household.
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.
⏰ Daily reminder that contributing to #OSS can be just a few words in some #documentation.
I've spent a few hours debugging an issue that hopefully no one else will encounter thanks to one word added in the documentation 🤞
Just discovered https://diataxis.fr/ "A systematic approach to technical documentation authoring." really good resource, been looking for something like this for a while. Found it on the rocm (AMD machine learning library) docs blog post #tech #documentation
Seeking #recommendations on #private #wiki options.
Anyone using internal #documentation #software you like?
(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.
2/2
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.
1/2
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 pledge to share this every few days until this trend cools down!
#programming #softwaredevelopment #softwareengineering #documentation #EffectiveCommunication
#DoNotUseVideosForTechnicalMaterial
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?
Maintenance of the Label Studio #opensource project through triaging issues and PRs, #documentation, and educational resources.
Most recently, this was through educating about the JSON format and new #GenerativeAI features.
#Design #Guides
UX design documentation guide · How documentation can promote teamwork, efficiency, and continuity https://ilo.im/14jh5y
_____
#Documentation #ProductStrategy #ProductDesign #UxDesign #WebDesign #DesignSystem #Checklist
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
Wow! Recently a colleague recommended the
all-in-one #API #documentation browser with offline mode and instant search: http://devdocs.io
And I like it! It seems to collect the docs of nearly all programming languages, make them very fast searchable and give them a clean layout 🙂