#readthedocs — Public Fediverse posts

Experimentally, it seems like pushing new "build style" semver tags is sufficient to get #ReadTheDocs / #RTD to update its 'stable' pointer. That'll probably do for now?

E.g., I cut Paramiko 5.0.0+rtd1 and pushed it to GitHub but nowhere else (as it is literally 5.0.0 + a change to my RTD config files which do not impact any users or even contributors, really) and I'm seeing a rebuild w/ its SHA 🎉

Still more friction than I remember, but at least it's better than making a whole new release!

Weird, I could /swear/ #ReadTheDocs' 'stable' version used to track branches only, but the docs and changelog imply it's been branches /or tags/ (and critically, /favoring the latter when both exist/) since like 2018? Am I high?

The behavior as-is makes it hard to push #RTD-only or doc-only changes w/o cutting a whole new tag (and of course, cutting a whole new tag w/o releasing any code to PyPI, looks weird).

I.e., I can't just push a minor config tweak to my 5.0 branch to fix an issue with the 'stable' docs.

Somewhat ironically, my own changelog setup still creates links to 'latest' instead of 'stable' 🙃 but 'stable' is the default otherwise…

One of the most hidden super-cool (sorry, born in the 70s) features of #tailwindcss is the `group` class. Put it on an outer div, then inside do a `group-hover:crazy colors` thing and be impressed. #readthedocs (at least once fully): https://tailwindcss.com/docs/hover-focus-and-other-states#styling-based-on-parent-state

One of the most hidden super-cool (sorry, born in the 70s) features of #tailwindcss is the `group` class. Put it on an outer div, then inside do a `group-hover:crazy colors` thing and be impressed. #readthedocs (at least once fully): https://tailwindcss.com/docs/hover-focus-and-other-states#styling-based-on-parent-state

#TreeTime #Trees #MindMap #Editor #OpenSource #FreeSoftware

In reaction to several turns of recent events, TreeTime is starting to move away from #GitHub to #Codeberg: https://codeberg.org/jkanev/treetime#readme

There will be a transition period in which both repositories will receive updates in parallel.

The installable packages in #Pypi, the webpage on https://tree-time.info, and the documentation in #readthedocs will stay unaffected.

Divine Documentation

Dad was about my age when he said that reading the manual was better than hypothesis driven button pressing. For teenage me, that took too long. Sure, I may have crashed a computer or two but following my gut got me there. Of course my gut isn’t that smart. In the decades preceding, devices had converged on a common pattern language of buttons. Once learned, the standard grammar of action would reliably deliver me to my destination. 

In programming I was similarly aided by the shared patterns across MATLAB, Python, R, Java, Julia, and even HTML. In the end however, dad was right. Reading documentation is the way. Besides showing correct usage, manuals create a new understanding of my problems. I am able to play with tech thanks to the people that took the effort and the care to create good documentation. This is not limited to code and AI. During the startup years, great handbooks clarified accounting, fundraising, and regulations, areas foreign to me.

I love good documentation and I write documentation. Writing good documentation is hard. It is an exercise in deep empathy with my user. Reaching into the future to give them all they need is part of creating good technology. Often the future user is me and I like it when past me is nice to now me. If an expert Socratic interlocutor is like weight training, documentation is a kindly spirit ancestor parting the mist. 

Maybe it’s something about being this age but now I try to impart good documentation practices to my teams. I also do not discourage pressing buttons to see what happens. Inefficient, but discovery is a fun way to spike interest.

Meanwhile, I’m reading a more basic kind of documentation. Writing English. Having resolved to write more, I’m discovering that words are buttons. Poking them gets me to where I want, but not always. Despite writerly ambitions, the basics are lacking. This became apparent recently when I picked up the book Artful Sentences by Virginia Tufte*. It’s two hundred and seventy pages of wonderful sentences dissected to show their mechanics. I was lost by page 5. The book is, temporarily, in my anti-library. 

So, I’m going to the basics, Strunk and White, and William Zinsser. I’m hoping that Writing to Learn (finished) and On Writing Well (in progress) provide sufficient context about reasons to write to make the most of S&W, for the how, then somewhere down the road, savor Tufte. 

* Those dastardly Tuftes are always making me learn some kind of grammar.

#AI #Business #ContinuousLearning #DevLife #Documentation #EmpathyInDesign #KnowledgeSharing #Leadership #LearningInPublic #ManualsMatter #OpenSource #philosophy #Programming #ReadTheDocs #science #SoftwareDevelopment #Startups #StrunkAndWhite #TechWriting #VirginiaTufte #WilliamZinsser #WritingWell

Divine Documentation

Dad was about my age when he said that reading the manual was better than hypothesis driven button pressing. For teenage me, that took too long. Sure, I may have crashed a computer or two but following my gut got me there. Of course my gut isn’t that smart. In the decades preceding, devices had converged on a common pattern language of buttons. Once learned, the standard grammar of action would reliably deliver me to my destination. 

In programming I was similarly aided by the shared patterns across MATLAB, Python, R, Java, Julia, and even HTML. In the end however, dad was right. Reading documentation is the way. Besides showing correct usage, manuals create a new understanding of my problems. I am able to play with tech thanks to the people that took the effort and the care to create good documentation. This is not limited to code and AI. During the startup years, great handbooks clarified accounting, fundraising, and regulations, areas foreign to me.

I love good documentation and I write documentation. Writing good documentation is hard. It is an exercise in deep empathy with my user. Reaching into the future to give them all they need is part of creating good technology. Often the future user is me and I like it when past me is nice to now me. If an expert Socratic interlocutor is like weight training, documentation is a kindly spirit ancestor parting the mist. 

Maybe it’s something about being this age but now I try to impart good documentation practices to my teams. I also do not discourage pressing buttons to see what happens. Inefficient, but discovery is a fun way to spike interest.

Meanwhile, I’m reading a more basic kind of documentation. Writing English. Having resolved to write more, I’m discovering that words are buttons. Poking them gets me to where I want, but not always. Despite writerly ambitions, the basics are lacking. This became apparent recently when I picked up the book Artful Sentences by Virginia Tufte*. It’s two hundred and seventy pages of wonderful sentences dissected to show their mechanics. I was lost by page 5. The book is, temporarily, in my anti-library. 

So, I’m going to the basics, Strunk and White, and William Zinsser. I’m hoping that Writing to Learn (finished) and On Writing Well (in progress) provide sufficient context about reasons to write to make the most of S&W, for the how, then somewhere down the road, savor Tufte. 

* Those dastardly Tuftes are always making me learn some kind of grammar.

#AI #Business #ContinuousLearning #DevLife #Documentation #EmpathyInDesign #KnowledgeSharing #Leadership #LearningInPublic #ManualsMatter #OpenSource #philosophy #Programming #ReadTheDocs #science #SoftwareDevelopment #Startups #StrunkAndWhite #TechWriting #VirginiaTufte #WilliamZinsser #WritingWell

Divine Documentation

Dad was about my age when he said that reading the manual was better than hypothesis driven button pressing. For teenage me, that took too long. Sure, I may have crashed a computer or two but following my gut got me there. Of course my gut isn’t that smart. In the decades preceding, devices had converged on a common pattern language of buttons. Once learned, the standard grammar of action would reliably deliver me to my destination. 

In programming I was similarly aided by the shared patterns across MATLAB, Python, R, Java, Julia, and even HTML. In the end however, dad was right. Reading documentation is the way. Besides showing correct usage, manuals create a new understanding of my problems. I am able to play with tech thanks to the people that took the effort and the care to create good documentation. This is not limited to code and AI. During the startup years, great handbooks clarified accounting, fundraising, and regulations, areas foreign to me.

I love good documentation and I write documentation. Writing good documentation is hard. It is an exercise in deep empathy with my user. Reaching into the future to give them all they need is part of creating good technology. Often the future user is me and I like it when past me is nice to now me. If an expert Socratic interlocutor is like weight training, documentation is a kindly spirit ancestor parting the mist. 

Maybe it’s something about being this age but now I try to impart good documentation practices to my teams. I also do not discourage pressing buttons to see what happens. Inefficient, but discovery is a fun way to spike interest.

Meanwhile, I’m reading a more basic kind of documentation. Writing English. Having resolved to write more, I’m discovering that words are buttons. Poking them gets me to where I want, but not always. Despite writerly ambitions, the basics are lacking. This became apparent recently when I picked up the book Artful Sentences by Virginia Tufte*. It’s two hundred and seventy pages of wonderful sentences dissected to show their mechanics. I was lost by page 5. The book is, temporarily, in my anti-library. 

So, I’m going to the basics, Strunk and White, and William Zinsser. I’m hoping that Writing to Learn (finished) and On Writing Well (in progress) provide sufficient context about reasons to write to make the most of S&W, for the how, then somewhere down the road, savor Tufte. 

* Those dastardly Tuftes are always making me learn some kind of grammar.

#AI #Business #ContinuousLearning #DevLife #Documentation #EmpathyInDesign #KnowledgeSharing #Leadership #LearningInPublic #ManualsMatter #OpenSource #philosophy #Programming #ReadTheDocs #science #SoftwareDevelopment #Startups #StrunkAndWhite #TechWriting #VirginiaTufte #WilliamZinsser #WritingWell

Divine Documentation

Dad was about my age when he said that reading the manual was better than hypothesis driven button pressing. For teenage me, that took too long. Sure, I may have crashed a computer or two but following my gut got me there. Of course my gut isn’t that smart. In the decades preceding, devices had converged on a common pattern language of buttons. Once learned, the standard grammar of action would reliably deliver me to my destination. 

In programming I was similarly aided by the shared patterns across MATLAB, Python, R, Java, Julia, and even HTML. In the end however, dad was right. Reading documentation is the way. Besides showing correct usage, manuals create a new understanding of my problems. I am able to play with tech thanks to the people that took the effort and the care to create good documentation. This is not limited to code and AI. During the startup years, great handbooks clarified accounting, fundraising, and regulations, areas foreign to me.

I love good documentation and I write documentation. Writing good documentation is hard. It is an exercise in deep empathy with my user. Reaching into the future to give them all they need is part of creating good technology. Often the future user is me and I like it when past me is nice to now me. If an expert Socratic interlocutor is like weight training, documentation is a kindly spirit ancestor parting the mist. 

Maybe it’s something about being this age but now I try to impart good documentation practices to my teams. I also do not discourage pressing buttons to see what happens. Inefficient, but discovery is a fun way to spike interest.

Meanwhile, I’m reading a more basic kind of documentation. Writing English. Having resolved to write more, I’m discovering that words are buttons. Poking them gets me to where I want, but not always. Despite writerly ambitions, the basics are lacking. This became apparent recently when I picked up the book Artful Sentences by Virginia Tufte*. It’s two hundred and seventy pages of wonderful sentences dissected to show their mechanics. I was lost by page 5. The book is, temporarily, in my anti-library. 

So, I’m going to the basics, Strunk and White, and William Zinsser. I’m hoping that Writing to Learn (finished) and On Writing Well (in progress) provide sufficient context about reasons to write to make the most of S&W, for the how, then somewhere down the road, savor Tufte. 

* Those dastardly Tuftes are always making me learn some kind of grammar.

#AI #Business #ContinuousLearning #DevLife #Documentation #EmpathyInDesign #KnowledgeSharing #Leadership #LearningInPublic #ManualsMatter #OpenSource #philosophy #Programming #ReadTheDocs #science #SoftwareDevelopment #Startups #StrunkAndWhite #TechWriting #VirginiaTufte #WilliamZinsser #WritingWell

Divine Documentation

Dad was about my age when he said that reading the manual was better than hypothesis driven button pressing. For teenage me, that took too long. Sure, I may have crashed a computer or two but following my gut got me there. Of course my gut isn’t that smart. In the decades preceding, devices had converged on a common pattern language of buttons. Once learned, the standard grammar of action would reliably deliver me to my destination. 

In programming I was similarly aided by the shared patterns across MATLAB, Python, R, Java, Julia, and even HTML. In the end however, dad was right. Reading documentation is the way. Besides showing correct usage, manuals create a new understanding of my problems. I am able to play with tech thanks to the people that took the effort and the care to create good documentation. This is not limited to code and AI. During the startup years, great handbooks clarified accounting, fundraising, and regulations, areas foreign to me.

I love good documentation and I write documentation. Writing good documentation is hard. It is an exercise in deep empathy with my user. Reaching into the future to give them all they need is part of creating good technology. Often the future user is me and I like it when past me is nice to now me. If an expert Socratic interlocutor is like weight training, documentation is a kindly spirit ancestor parting the mist. 

Maybe it’s something about being this age but now I try to impart good documentation practices to my teams. I also do not discourage pressing buttons to see what happens. Inefficient, but discovery is a fun way to spike interest.

Meanwhile, I’m reading a more basic kind of documentation. Writing English. Having resolved to write more, I’m discovering that words are buttons. Poking them gets me to where I want, but not always. Despite writerly ambitions, the basics are lacking. This became apparent recently when I picked up the book Artful Sentences by Virginia Tufte*. It’s two hundred and seventy pages of wonderful sentences dissected to show their mechanics. I was lost by page 5. The book is, temporarily, in my anti-library. 

So, I’m going to the basics, Strunk and White, and William Zinsser. I’m hoping that Writing to Learn (finished) and On Writing Well (in progress) provide sufficient context about reasons to write to make the most of S&W, for the how, then somewhere down the road, savor Tufte. 

* Those dastardly Tuftes are always making me learn some kind of grammar.

#AI #Business #ContinuousLearning #DevLife #Documentation #EmpathyInDesign #KnowledgeSharing #Leadership #LearningInPublic #ManualsMatter #OpenSource #philosophy #Programming #ReadTheDocs #science #SoftwareDevelopment #Startups #StrunkAndWhite #TechWriting #VirginiaTufte #WilliamZinsser #WritingWell

I have asked #GPT-4.0 to translate a news report from Dutch to German for me because I wanted to inform my family about current debates in the Netherlands. I was surprised that #ChatGPT started a #deepsearch although I had not actively selected this feature. I had vaguely heard about it but never used it before, and I am still wondering what it actually does. I will have to #readthedocs for sure! But has anyone got insights they'd like to share? Deep search sounds a lot like #energywaste to me.

Coming from #MkDocs on #ReadTheDocs , I think about migrating our projects user manual to #Asciidoc using #asciidoctor and/or #antora .

But I wonder if there is a service like #readthedocs for #asciidoc based manuals available for #OpenSource or #foss projects.

Important is that those platforms do support @Codeberg (#forgejo aka #gita ) code hosting, instead of Microsoft GitHub.

I came across something recently that basically stressed the importance of understanding the tools you use on a daily basis to get the most out of them. It suggested that you need to get familiar with the primary sources of docs as well and not just distilled summaries that hold your hand and give you a generic solution to one particular problem your trying to solve. With that in mind, my reading list lately has been the official docs for #neomutt, #irssi, #i3wm, #opnsense, #tmux. I think this is more important than ever when it's so easy to use an #llm to search for information.

#learning #readthedocs

«Вымрут» ли печатные пользовательские инструкции?

В эпоху цифровизации техническая документация меняет свои формы и функции. Печатные издания, когда-то считавшиеся основным источником информации, постепенно уступают место онлайн-форматам. Однако остаётся вопрос: есть ли будущее у печатных документов, или их неизбежно ждёт забвение? В этой статье мы разберём преимущества и недостатки обоих форматов, а также рассмотрим современные инструменты, которые помогают создавать качественную и удобную документацию.

https://habr.com/ru/companies/documenterra/articles/868362/

#цифровизация #техническая_документация #печатные_тексты #онлайн #интерактивность #инструменты #notion #readthedocs #gitbook #slack

I'm seeking experiences in multi-language #documentation, e.g in #Sphinx #SphinxDoc, #MkDocs, …

What system/tool can you recommend? How do you handle contributions in case a person not speaking English (which is the 'main' language) wants to add some section?

The aim is to create docs for #tryton. Thus as a bonus we need/want multi-country docs, too. E.g. for describing country-specific taxing — where we don't need information for France in the English master neither in the German translation, but the German translation needs different parts for Germany, Austria and Switzerland. (And things get worse counting in all the countries speaking English or French.) If you have experiences with this, please share.

#followerpower #PleaseBoost #ReadTheDocs #RTD

I have created a Read The Docs site for Mecrisp Ice, which is a family of 16, 32 and 64 bit soft core Forth processors written in Verilog and based on the J1 stack machine.

https://mecrisp-ice.readthedocs.io

@Mecrisp #mecrisp #fpga #forth #j1 #stackmachine #readthedocs

🎉 Release 2.0 of the #python package #pyam_iamc for #dataviz and #scenario analysis of #IntegratedAssessment, #EnergySystems & #MacroEnergy models.

Code #OpenSource on #GitHub, docs & tutorials hosted on #ReadTheDocs, discussion fora via groups.io and #Slack.

⚠️The new release removes support for #python earlier than 3.10 for easier maintenance and streamlined development going forward...

Check out the release details at https://github.com/IAMconsortium/pyam/releases/tag/v2.0.0

Let's try this: Dear #lazyweb / #lazyfedi, what is the current go-to if I have to/want to write application #documentation for #endusers?
It is a #rust application, that does contain a lot of #rustdoc already, but that is very specific to the code, like api/developers doc. It is not end user stuff.

So, what to do? Own branch and something in it, that then gets rendered on a Github-or-similar page? A .md file used with #mkdocs? Using #readthedocs and their #sphinx based setup (also their examples are pretty python related). Somehting else?

I would like to stay as near to the code as I can. *Ideally* it would be rustdoc comments, but that can't be, as that is used for the developers doc already. "Just" a file besides, maybe in doc/ sounds better than whole new branch? Also, would be nice if I do NOT have to learn a complete new markup language.

Any #suggestions?

To review the (draft) update of national #SSP projections for #GDP and #population, you can...

1. View the data via our interactive #ScenarioExplorer hosted by the #IIASA #ScenarioServices team
2. Download the full dataset as xlsx
3. Access the data via our #Python or #Rstats API

And with our #opensource package #pyam_iamc, it's as easy as the snippet below...
... to get something that's just like a #pandas #DataFrame - but better!

#ReadTheDocs at https://pyam-iamc.readthedocs.io

Just in time for the #openmod workshop hosted by the #IIASA #Energy #Climate & #Environment program...

🎉New release v1.8 of our #opensource #python package #pyam_iamc for #scenario analysis & #dataviz!

1. Jonas Hirsch & Matt Gidden refactored the internal #pandas data handling, so initializing an #IamDataFrame is now up to 3x faster for large datasets!
2. @PietroMonticone fixed a few typos in the #tutorials...

#ReadTheDocs 👉 https://pyam-iamc.readthedocs.io/

I'm obsessed with good #documentation and the Routinator user manual on #ReadTheDocs is my pride and joy.

We worked very hard to seamlessly integrate the manual page into it as well, allowing us to automatically link command line options, but we also wanted it to be the canonical source for building the the manpage with rst2man. This saves us from keeping content in sync and messing with troff(1).

https://github.com/NLnetLabs/routinator/blob/main/doc/manual/source/manual-page.rst

#WriteTheDocs #TechnicalWriting #TechnicalDocumentation #OpenSource

There's been tremendous progress to #freethemodels for #energysystems modelling! However, when it comes to #dataprocessing, scenario analysis & #dataviz, there's much less collaborative effort...

If you use #python for working with #energy or #climate scenarios, check out our #opensource package #pyam_iamc at https://pyam-iamc.readthedocs.io - we have plenty of tutorials to help you get started!
#github #pypi #conda #readthedocs

Has anyone worked with #EthicalAds by #ReadTheDocs and can tell me how the `data-ea-force-ad` attribute should be used? I can't get it to show anything and I don't want paid ads to pop up when I'm testing changes locally.

Is there a way to get #ReadTheDocs documentation onto #Devhelp? Would very much increase the scope! :gnomewhite: