Just discovered 'presenterm' and have to try it out. I like #terminal and #Rust, so I might need it sometime. The nice thing about this #RustLang solution is that it uses #markdown and I also like this a lot to create #documentation and #presentation.
Check this video tutorial from Justin Flory if you missed the latest Docs workshop.
Fedora Docs monthly workshop presented by Justin Flory, Fedora Community Architect, provided us with wealth of knowledge and hands-on experience on Documentation.
Spend 6 hours squize out 4 minutes more minutes of the rendering process of #typo3 changelog rendering. By now the rendering process without cache takes 2.15 min on my laptop.
This does not only save time but also a lot of computing power. How much CO2 reduction would this be in the long term? #php#documentation
#ReleaseFriday 🚀 - This week's #ThingUmbrella releases are mainly related to ShaderAST & ongoing repo-wide documentation updates of all 190 packages...
https://thi.ng/shader-ast — Added polymorphic syntax sugar versions of various math ops to simplify "self-assignments" aka ops in the form of x = x+ 2, which would in shader AST syntax looked like assign(x, add(x, 2)), now addSelf(x, 2)... See changelog & docs for details of supported ops.
https://thi.ng/shader-ast-stdlib — The "standard library" for https://thi.ng/shader-ast has had several new additions of useful helpers & metaprogramming tools, e.g. a new branches() function (see screenshot) to simplify n-ary A/B testing of params (or debugging of shader outputs) as is commonly done by e.g. visualizing different versions as columns based on fragment position. Other additions include surface normal calculation from a 2D terrain/grayscale texture (e.g. for GIS or fluid sims), float packing/unpacking (to/from 8bit/channel RGBA textures as a lot of mobile devices still don't support float render textures in WebGL)...
https://thi.ng/shader-ast-optimize — This package is used to apply various optimizations on a given shader AST program (or expression). Recursive constant folding has been extended to more ops & built-in functions. There's also a new wrapper function defOptimized() which can be used in place of defMain() to create auto-optimized shader main functions. The new version also has several bug fixes and more tests... See updated readme for examples.
As mentioned in earlier toots, I've also been doing several large rounds/commits of general documentation related updates/revamps, incl. updating all code examples in readmes & API docs to provide all required import statements, writing a new tooling (see below) to extract said code blocks from their original files and export them to their own source files for easier testing/trying them out from the command line. That work is only partially completed (with still hundreds of files to edit/update), but if you've got a clone of the https://thi.ng/umbrella repo, you can already try it out by running yarn tool:tangle (to extract examples from API docs in source files) or yarn doc:readme (to extract from readmes). In both cases, make sure your first build everything via yarn build. The tools will log where each of the examples is written to. Once I'm done, there will be ~800 example files extracted via this process... 💪
Been thinking again about recent #ThingUmbrella survey results and also what @inthehands emphasized recently, i.e. that "Software development is an intensely social discipline.". I fully agree.
Too much power in a programming language/tooling means no or very few struggles. On the other hand, very few struggles also mean very little incentives for community to form/grow, to exchange, to debate, to contribute... (basically also one of the more indirect morals of The Lisp Curse)
60-80% of the survey feedback (finaly comments) are along the lines of "thi.ng is amazing", "thi.ng has been a huge inspiration", "a real treasure trove", "love the project", "thi.ng is awesome and a joy to work with"... Hearing this makes my heart jump for joy!
Yet, I'm also keenly aware there are aspects of these projects which cause people to "struggle", and I'm also constantly working on improving the DX & docs for everyone, including creating new custom tooling and automation...
Today, I spent most of my time on new tooling to extract the almost 800 code examples embedded in API docs to individual source files, in order to run/try them directly from the command line... With the vast scope of the larger project, this means each time there's a new update/tool like this, there're 100s (sometimes 1000+) of source files to check, to edit and verify, mostly manually (today I managed write the tool, but only updated a few dozen source files...)
I'm often feeling the effort & time spent on these tasks is becoming harder to justify, if there's so little feedback for all the documentation materials which are actually there. The mostly vague complaints about docs missing, being confusing or difficult topics are not really helpful to improving these aspects. I also can't help but wonder why there's been so very, very little offers to help with that (if people have issues, the least is to be constructive about it...)
How do other OSS project maintainers deal with this? Has this ever been an issue for you? Apart from investing even more time in these things, what else can I do? The 150+ example projects don't seem to help either... Part of this discussion feels like catch-22...
In social policy, Chesterton's fence is a "principle that reforms should not be made until the reasoning behind the existing state of affairs is understood."
It has a lot of overlap with internal technical documentation: if you don't know why some decisions and implementations were made, it's very challenging to change things.
While we joke, that software architects only need to know how to draw boxes (and not how to program anything), I quite dislike when the opposite happens of programmers not knowing how to draw boxes (and only how to program).
Please write documentation for your most central concepts.
Your future-self and anyone after you will be thankful.
Just finished manually updating in total ~780 code blocks & snippets in over 400 files (readme's & source code), adding import statements of all used functions & updating comments over the past week (in addition to the 1st round last weekend[1])... Would be super great to hear if people find this useful/helpful (other than the two who were proposing it in the survey feedback)... 😉
Over the next months I will do another pass over the readmes to make it easier to auto-extract various code examples[2], to try them out and/or test them... Also going forward, new code examples added to readme's will aim to support this feature, but there's a huge backlog of existing ones too.
Hey folks, this is your irregularly scheduled reminder that I'm on the job market. Looking for permanent or contract stuff in the developer docs space as a senior individual contributor or team lead. Live community. Love remote work. Laugh when I'm able to help other people build stuff.
Thanks to everyone who has already passed along links, made introductions or boosted my posts.
Btw. It was also #ReleaseSunday yesterday and as a direct & immediate result from a good criticism received via the community survey, I've updated all 350+ code snippets in 275+ source files/docs of all 190 https://thi.ng/umbrella libraries. Each snippet now includes imports for all functions/constants used, incl. those from other packages (if there are)... The updated docs have also been published on https://docs.thi.ng/. Hope that helps! If you do run into any mistakes & omissions, please get in touch! 🙏
Obviously, this doesn't fix other issues with the docs, but many of them are the result of other fundamental issues with TypeDoc & TypeScript's language server (e.g. treating arrow functions and/or functions annotated with type aliases as 3rd class citizens). I do not have the bandwidth to re-organize a massive project like this around the quirks/bugs of 3rd party infrastructure, but I'm always open to suggestions for how the situ can be improved... Many times I've been pondering and even starting work on a custom doc generator (incl. a ton more metadata, diagrams, cross-references, links to related functions [in other packages]), but I just cannot justify working on this at this stage...
You have no idea how much I love and appreciate concrete helpful & constructive feedback like "put import statements in code snippets" compared to handwavy & obtuse comments like "the docs are pretty bad..." or "examples are all for wild or out there things but what I need are tutorials on the basics". None of the hundreds of example projects & snippets cover those, are you sure?!
Concrete feedback (like the former) actually helps kickstarting things and leads to improving the situation for other users/everyone! I.e. I've already started updating the code snippets in all doc strings across all 190 libraries and I'm going to push new releases in the next couple of days! Great! 🙏🚀
If people really want thi.ngs to improve, at the very least they need to report what exactly is wrong/weak with the docs (preferably with examples), or explain which "basics" should be focused on more... There's an issue tracker and discussion forum[1]. I've been repeatedly asking for feedback here too...
Going hand in hand with this, the survey[2] question "Have you ever contributed to any thi.ng project in any way?" has a big fat ZERO for the "documentation" answer choice. I don't know why it's soo very hard to even just entice people providing some constructive comments, if helping out in other ways is out of the question...
In general, preliminary feedback collected in the survey so far seems to indicate these projects really are like Marmite[3] — people either absolutely love it or hate it, with seemingly not much middle ground... Go figure! Maybe it's a sign of the times...
The result of this is a feeling of being stuck between a rock and a hard place. No matter how much energy (1000s of hours in the past 2 years alone) I've already been investing in providing/improving docs (>50k words in just the readme's), creating/updating docstrings, examples, snippets, diagrams & including links for further reading... it all just doesn't seem to register or is getting shrugged off as non-helpful and I truly don't know if spending even more time/energy/savings on any of this really even worth the effort anymore... Where is the bar for open source projects, esp. those not run be corporations?
Fedora Docs monthly workshop today presented by Justin Flory @jwf , Fedora Community Architect, provided us wealth of knowledge and hands-on experience on Documentation.
Thanks all for joining. I'll upload recorded footage by 2 March on PeerTube channel.
See you next month on the last Thursday of March. I will share the link soon here in Mastodon.
Heads up: for the past couple of weeks @bitsavers has been adding tons of new documents to the archive. For example, have a look at the sections on Microsoft, IBM, DEC, and Ampex.
dem vielen Wasser, das hier überall auf Wiesen und Feldern steht
meiner Affinität zu Keyboards als primäres Interaktionselement mit Computern …
… und welchen Keyboard-Shortcut ich in Firefox schmerzlich vermisse
der macOS App Rectangle
dem Fork von nginx zu freenginx und wie ich am Wochenende nach 19 Jahren ausschließlich nginx-Nutzung mit Caddy erstmals einen anderen Webserver angeschaut habe und seit dem ziemlich begeistert bin
einer Anleitung wie man gute technische Dokumentation schreibt
mkcert und wie es xca als Management-Tool für meine lokale CA abgelöst hat