Current status: Updating the https://thi.ng/geom readme to give a better overview of the full extensive API, ahead of the v8 release (soon)... Attached are screenshots of three sections of the readme showing:
list of 32 shape types (both 2D and 3D)
list of 54 polymorphic functions/operations to manipulate/convert/analyze shapes & shape hierarchies
list of additional 40 shape creation functions
Still to come: Documenting the bundled preset implementations of:
vertex convolution kernels (3)
curve subdivision strategies (8)
polygon/polyline to bezier conversion strategies (3)
polygon tessellators (9)
(...and how most of these can be combined & applied iteratively. Some of the recent/existing examples are already hinting at the potential...)
I'm investigating options that are available to create a table of contents in #markdown, really wondering what people are using to create that when writing markdown based docs.
With the job market getting tougher by the day, there’s a rising belief among tech writers that their role is “too niche” and a “dead-end job”. I think that’s the wrong way of looking at our profession — at any profession. Let me cast aside that dark veil of pessimism and offer an alternative viewpoint, that of tech writing as a platform to other professions, one that let you move laterally with just a bit of curiosity and courage.
I am fortunate that my manager recognises this critical juncture in technical writing and has given me substantial time to reimagine my job.
I spoke about the benefits of working in the space between professional silos in my Linux Conference talk a few years ago: When STEM Becomes STEAM We All Benefit https://m.youtube.com/watch?v=oEX-F5SxwrU
I really hate haddocks' eyes in code #documentation 'Defines the Foo class', 'Provides an implementation of the foo plugin'. No. It IS the Foo class. It IS the foo plugin.
Why didn't anyone tell me about https://devdocs.io? You convert the site into a web application, enable the packages you need, download for offline access and enjoy fuzzy search, speed and smooth operation for free.
phpDocumentor 3.5 is here! With better Guides support and now fully functional RST! Automatic generated class diagrams by querying your code base and much more!
The series provides an #InDepthAnalysis of the idea that human rights violations, armed conflict & #war cause #psychological & #psychiatric outcomes, using the Kingdom’s tragic past to explore themes.
A young developer who never used Windows 98 back in the day stumbled upon an introductory book on the operating system and posted his impressions on skimming it, which brought him joy. He wrote:
"I was also left with the impression that perhaps I would like more software to come with a physical manual."
Hey if you want to discuss anything about #documentation please sign up at the board at the #DocSummit (room 317) - you can also sign up for lightning talks (documentation related)
Interesting. Several Canonical projects are using Discourse as their #documentation platform.
As with documentation using wikis, it's nearly the opposite of Documentation As Code. Instead of benefiting from a relationship between documentation, the software, its versioning and CI platforms, it builds a direct relation between documentation, support and community.
Would be nice to have a LLM that you can train locally with your organization documentation, to be able to have an interface to easily find that information buried in decades of documents #LLM#MachineLearning#documentation#FOSS
I think this is something all #golang devs should be aware of to avoid similar vulnerabilities.
The language is kind of amazing:
Step 3. only applies if there is a parent path to be eliminated together with the subsequent “..” (“/foo/..” -> “/“)
Step 4. only applies to “rooted” (absolute) paths, so “/../foo” would become “/foo”, but “../“ is left untouched (as there is no relative parent path to eliminate either).
This makes the docs technically correct (“the best kind of correct!”), but even with the solution at hand it took some head scratching to figure out the true meaning.
I was building some flatpack furniture the other day (my life is so glamorous) when I came across an interesting example of how not to write technical documentation. Drill a hole in part A and insert part B once you have ensured part C has been aligned after its connection to A. Most people can […]
I was building some flatpack furniture the other day (my life is so glamorous) when I came across an interesting example of how not to write technical documentation.
Drill a hole in part A and insert part B once you have ensured part C has been aligned after its connection to A.
Most people can handle reading a whole sentence to figure out what's going on. But, after a tiring day of building, it is somewhat annoying having to juggle instructions into actions.
Most readers will assume that instructions are written in linear time. Do this, then that. But that example is non-linear. What it is trying to say is:
Connect part C with part A. Then align part C and part A. Then drill the hole in part A. Then insert part B into part A.
It is slightly less interesting writing. But it presents all the actions in the order they need to be taken.
I see this temporally-mixed anti-pattern all the time. A typical example of this in technical documentation is:
Select Print from the File menu.
A simpler, clearer, and less ambiguous way of writing that is:
Open the File menu. Select Print.
Another similar example of confusing writing is:
Go to File → Print → Settings if you need to change the paper size.
Again, this places cognitive burden on the reader. If they want to understand if the instruction is relevant to them, they have to read the entire sentence. When faced with dozens of sentences, this can become confusing. The solution is:
If you want to do X, then do Y...
Immediately the reader knows that they can skip this sentence because they don't want to do X.
As technical writers, we sometimes want to craft eloquent prose. We long for glorious and intricate sentences. We tire of the monotony of linear writing.
Tough. We need to get over ourselves. Go write that epic fantasy novel you've been thinking about. The job of a technical writer isn't to entertain, enliven, or delight the reader. The job is to give them instructions in an easy to follow format, reducing the amount of cognitive burden they have, and making it quick to find the information they need.