Aneesh Sathe<p><strong>Divine Documentation</strong></p><p class="">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 <em>that</em> 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. </p><a href="https://aneeshsathe.com/wp-content/uploads/2025/07/image-from-rawpixel-id-441318-jpeg.jpg" rel="nofollow noopener" target="_blank"></a>Image of a nebula taken by the Hubble Telescope.<p>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.</p><p>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. </p><p>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.</p><p>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. </p><p>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. </p><p class="">* Those dastardly Tuftes are always making me learn some kind of grammar.</p><p><a rel="nofollow noopener" class="hashtag u-tag u-category" href="https://aneeshsathe.com/tag/ai/" target="_blank">#AI</a> <a rel="nofollow noopener" class="hashtag u-tag u-category" href="https://aneeshsathe.com/tag/business/" target="_blank">#Business</a> <a rel="nofollow noopener" class="hashtag u-tag u-category" href="https://aneeshsathe.com/tag/continuouslearning/" target="_blank">#ContinuousLearning</a> <a rel="nofollow noopener" class="hashtag u-tag u-category" href="https://aneeshsathe.com/tag/devlife/" target="_blank">#DevLife</a> <a rel="nofollow noopener" class="hashtag u-tag u-category" href="https://aneeshsathe.com/tag/documentation/" target="_blank">#Documentation</a> <a rel="nofollow noopener" class="hashtag u-tag u-category" href="https://aneeshsathe.com/tag/empathyindesign/" target="_blank">#EmpathyInDesign</a> <a rel="nofollow noopener" class="hashtag u-tag u-category" href="https://aneeshsathe.com/tag/knowledgesharing/" target="_blank">#KnowledgeSharing</a> <a rel="nofollow noopener" class="hashtag u-tag u-category" href="https://aneeshsathe.com/tag/leadership/" target="_blank">#Leadership</a> <a rel="nofollow noopener" class="hashtag u-tag u-category" href="https://aneeshsathe.com/tag/learninginpublic/" target="_blank">#LearningInPublic</a> <a rel="nofollow noopener" class="hashtag u-tag u-category" href="https://aneeshsathe.com/tag/manualsmatter/" target="_blank">#ManualsMatter</a> <a rel="nofollow noopener" class="hashtag u-tag u-category" href="https://aneeshsathe.com/tag/opensource/" target="_blank">#OpenSource</a> <a rel="nofollow noopener" class="hashtag u-tag u-category" href="https://aneeshsathe.com/tag/philosophy/" target="_blank">#philosophy</a> <a rel="nofollow noopener" class="hashtag u-tag u-category" href="https://aneeshsathe.com/tag/programming/" target="_blank">#Programming</a> <a rel="nofollow noopener" class="hashtag u-tag u-category" href="https://aneeshsathe.com/tag/readthedocs/" target="_blank">#ReadTheDocs</a> <a rel="nofollow noopener" class="hashtag u-tag u-category" href="https://aneeshsathe.com/tag/science/" target="_blank">#science</a> <a rel="nofollow noopener" class="hashtag u-tag u-category" href="https://aneeshsathe.com/tag/softwaredevelopment/" target="_blank">#SoftwareDevelopment</a> <a rel="nofollow noopener" class="hashtag u-tag u-category" href="https://aneeshsathe.com/tag/startups/" target="_blank">#Startups</a> <a rel="nofollow noopener" class="hashtag u-tag u-category" href="https://aneeshsathe.com/tag/strunkandwhite/" target="_blank">#StrunkAndWhite</a> <a rel="nofollow noopener" class="hashtag u-tag u-category" href="https://aneeshsathe.com/tag/techwriting/" target="_blank">#TechWriting</a> <a rel="nofollow noopener" class="hashtag u-tag u-category" href="https://aneeshsathe.com/tag/virginiatufte/" target="_blank">#VirginiaTufte</a> <a rel="nofollow noopener" class="hashtag u-tag u-category" href="https://aneeshsathe.com/tag/williamzinsser/" target="_blank">#WilliamZinsser</a> <a rel="nofollow noopener" class="hashtag u-tag u-category" href="https://aneeshsathe.com/tag/writingwell/" target="_blank">#WritingWell</a></p>
eupolicy.social is one of the many independent Mastodon servers you can use to participate in the fediverse.
This Mastodon server is a friendly and respectful discussion space for people working in areas related to EU policy. When you request to create an account, please tell us something about you.
Administered by:
Server stats:
197active users
eupolicy.social: About · Profiles directory · Privacy policy
Mastodon: About · Get the app · Keyboard shortcuts · View source code · v4.4.3
#readthedocs
0 posts · 0 participants · 0 posts today
Monika Barget<p>I have asked <a href="https://akademienl.social/tags/GPT" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>GPT</span></a>-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 <a href="https://akademienl.social/tags/ChatGPT" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>ChatGPT</span></a> started a <a href="https://akademienl.social/tags/deepsearch" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>deepsearch</span></a> 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 <a href="https://akademienl.social/tags/readthedocs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>readthedocs</span></a> for sure! But has anyone got insights they'd like to share? Deep search sounds a lot like <a href="https://akademienl.social/tags/energywaste" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>energywaste</span></a> to me.</p>
Zhian N. Kamvar<p>I'm in a situation where an organization has a <a href="https://hachyderm.io/tags/ReadTheDocs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>ReadTheDocs</span></a> website registered as `<project>.io` (via <a href="https://hachyderm.io/tags/NameCheap" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>NameCheap</span></a>). Note that no one in this organization are experts or even practitioners of web publishing. People are realizing that the documentation site is not the best landing page and want to do two things:</p><p>1. move the documentation site to `docs.<project>.io`<br>2. set `<project>.io` to host the landing page built on <a href="https://hachyderm.io/tags/GitHub" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>GitHub</span></a> with links out to `<project>.io`</p><p>The question is: how the heck does one go about doing this without borking everything? It's clear that external links to the documentation would need to change, but in the meantime, I can see the following:</p><p>1. register `docs.<project>.io` and add that to the domains in <a href="https://hachyderm.io/tags/ReadTheDocs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>ReadTheDocs</span></a><br>2. set `<project>.io` as the CNAME for the GitHub site<br>3. add JavaScript to the 404 page that detects if the link is attempting to point to the documentation site and provide the correct redirect.</p><p>Is there anything else that I'm missing? <a href="https://hachyderm.io/tags/Web" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>Web</span></a> <a href="https://hachyderm.io/tags/DNS" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>DNS</span></a></p>
Kevin Bowen :xfce:<p>About 2 or 3 years ago, I had some brave soul step up and volunteer to convert the <a href="https://fosstodon.org/tags/Xfce" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>Xfce</span></a> <a href="https://fosstodon.org/tags/documentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>documentation</span></a> over to the .rst format to publish to <a href="https://fosstodon.org/tags/readthedocs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>readthedocs</span></a> </p><p>I was busy at the time; but, I went ahead and set up the initial repos & created the workflow that would allow them to publish the docs on the platform.</p><p>IIRC, they lasted several weeks and a handful of docs before they disappeared.</p><p>It's definitely not glamorous work.😞</p>
🍒🌳 Hartmut Goebel<p>I'm seeking experiences in multi-language <a href="https://nerdculture.de/tags/documentation" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>documentation</span></a>, e.g in <a href="https://nerdculture.de/tags/Sphinx" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>Sphinx</span></a> <a href="https://nerdculture.de/tags/SphinxDoc" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>SphinxDoc</span></a>, <a href="https://nerdculture.de/tags/MkDocs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>MkDocs</span></a>, …</p><p>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?</p><p>The aim is to create docs for <a href="https://nerdculture.de/tags/tryton" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>tryton</span></a>. 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.</p><p><a href="https://nerdculture.de/tags/followerpower" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>followerpower</span></a> <a href="https://nerdculture.de/tags/PleaseBoost" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>PleaseBoost</span></a> <a href="https://nerdculture.de/tags/ReadTheDocs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>ReadTheDocs</span></a> <a href="https://nerdculture.de/tags/RTD" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>RTD</span></a></p>
Zhian N. Kamvar<p>Like, I see the benefit of working with rye for setting up new projects and working with well-formed ones, but it's surprisingly difficult to use with <a href="https://hachyderm.io/tags/ReadTheDocs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>ReadTheDocs</span></a> because it seems like it wants you to always do things its way and gets upset when you don't.</p>
Zhian N. Kamvar<p>Okay, <a href="https://hachyderm.io/tags/python" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>python</span></a> people, how does one get <a href="https://hachyderm.io/tags/rye" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>rye</span></a> to work well with <a href="https://hachyderm.io/tags/ReadTheDocs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>ReadTheDocs</span></a>?</p><p>I'm having a bear of a time because rye complains any time I try to do `rye init` because pyproject.toml exists, but then it complains when I try `rye sync` that it could not write the production lock file....</p><p>I just want a `.venv/` folder so that I can run `pip -m install -r docs/requirements.txt` and the python with my <a href="https://hachyderm.io/tags/Mac" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>Mac</span></a> is 3.9, but the project requires 3.10 at least :blobfoxrage:</p>
Zhian N. Kamvar<p>So any time I try to build a <a href="https://hachyderm.io/tags/ReadTheDocs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>ReadTheDocs</span></a> site locally, I keep getting template errors from <a href="https://hachyderm.io/tags/Sphinx" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>Sphinx</span></a>. Many of the solutions say "just install the theme manually and it will work," but this is not the case for me.</p><p>Anybody have any tips?</p><p><a href="https://github.com/readthedocs-examples/example-sphinx-basic/issues/7" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://</span><span class="ellipsis">github.com/readthedocs-example</span><span class="invisible">s/example-sphinx-basic/issues/7</span></a></p><p><a href="https://hachyderm.io/tags/python" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>python</span></a> <a href="https://hachyderm.io/tags/RTD" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>RTD</span></a></p>
Ben Ramsey<p><span class="h-card" translate="no"><a href="https://phpc.social/@awoodsnet" class="u-url mention" rel="nofollow noopener" target="_blank">@<span>awoodsnet</span></a></span> It’s hosted on <a href="https://phpc.social/tags/ReadTheDocs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>ReadTheDocs</span></a>, using their docs template and Sphinx to generate them. </p><p><a href="https://readthedocs.org" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://</span><span class="">readthedocs.org</span><span class="invisible"></span></a></p><p>The README in my docs folder goes into more detail: <a href="https://github.com/ramsey/uuid/tree/4.x/docs" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://</span><span class="ellipsis">github.com/ramsey/uuid/tree/4.</span><span class="invisible">x/docs</span></a></p>
carlyn<p>Part 10: Turns out yesterday was a Reading Day. I have the libraries up and running, but it’s time to truly get the picture as to why USD is even a thing, and what made Apple choose it. A lot of the existing literature is for VFX folks, which I am not, so in addition to my Top Pick references there’s some added color for programmers. </p><p><a href="https://www.whynotestflight.com/excuses/hello-usd-part-10-reading-day/" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://www.</span><span class="ellipsis">whynotestflight.com/excuses/he</span><span class="invisible">llo-usd-part-10-reading-day/</span></a></p><p>If you watch nothing else (39 min): <a href="https://www.nvidia.com/en-us/on-demand/session/gtcspring23-s52054/" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://www.</span><span class="ellipsis">nvidia.com/en-us/on-demand/ses</span><span class="invisible">sion/gtcspring23-s52054/</span></a></p><p>Top WAT: <a href="https://developer.nvidia.com/isaac-sim" rel="nofollow noopener" translate="no" target="_blank"><span class="invisible">https://</span><span class="">developer.nvidia.com/isaac-sim</span><span class="invisible"></span></a></p><p><a href="https://mastodon.social/tags/nVidiaUSD" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>nVidiaUSD</span></a> <a href="https://mastodon.social/tags/USD" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>USD</span></a> <a href="https://mastodon.social/tags/OpenUSD" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>OpenUSD</span></a> <a href="https://mastodon.social/tags/ReadTheDocs" class="mention hashtag" rel="nofollow noopener" target="_blank">#<span>ReadTheDocs</span></a></p>
TrendingLive feeds
Mastodon is the best way to keep up with what's happening.
Follow anyone across the fediverse and see it all in chronological order. No algorithms, ads, or clickbait in sight.
Create accountLoginDrag & drop to upload