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.
#TechnicalWriting#DITA#XML#DITAXML#Documentation#InformationArchitecture#StructuredAuthoring: "DITA is defined in its specification as “an XML-based architecture for authoring, producing, and delivering topic-oriented, information-typed content that can be reused and single-sourced in a variety of ways”. Originally developed by IBM in the early 2000s, DITA stands for Darwin Information Typing Architecture. “Darwin” refers to the naturalist Charles Darwin and his theory of evolution, reflecting DITA’s principles of specialization, inheritance, and adaptation.
DITA topics are standalone, context-free blocks of content, with content types kept clearly separate. There are three main topic types in DITA, all of which are inherited from the base topic type <topic>:
<concept>: background information that users must know before using the product
<task>: step-by-step instructions that users need to perform a task
<reference>: product specifications, commands, or other reference material
You create a document by selecting which existing topics should be reused and referencing them in what’s called a DITA map (similar to a table of contents).
Being an open standard, DITA has no proprietary restrictions. But while you’re not forced to buy a specific tool to use it, commercial XML editors have many features, such as visual editing and validation, that make writing DITA content much easier."
This is your reminder that we're just over two weeks out from the talk proposal deadline for Write the Docs Atlantic, an online conference about documentation.
Today, #Portugal is celebrating 50 years since the #revolution against dictatorship and fascism. This #article tells the stories about what kind of information the state #police (PIDE) collected about its citizens. It tells the stories of 6 people with #documentation from the #archives
Given the troubling times we're living through and the far right growing in Portugal itself, is it still possible to hold the values our parents and grandparents fought for in 1974?
I was wondering if comments alongside source code are not read for reasons other than them being likely to be out of date. Maybe its because ... syntax highlighting makes them less readable?
#TechnicalWriting#SoftwareDocumentation#Documentation: "Even if you have the same title, you can have different experiences with your career and learn different skillsets if you seek out different team sizes, company stages, reporting structures, and working environments.
Identifying that variation has been crucial for me as I’ve stared down a lifelong career doing “just writing”. Did I really want that? Thankfully, technical writing doesn’t look the same everywhere, and that variation is what keeps it exciting for me.
In chatting about next steps in a technical writing career with a mentee, we came up with the following list of experiences and job situations that could be on a bucket list for technical writers.
What types of experiences and job situations might make sense on a bucket list look like for technical writers? I’m still developing my own, but I wrote up this list to serve as inspiration:"
This documentation details adding mastodon-post (by @DavidDarnes) into a static site generated by the Nikola #ssg in order to link back to discussion in the #fediverse
"The Aruba Collection (Coleccion Aruba) is the documentary heritage portal for the island nation of Aruba, and is the result of the cooperation of Aruba's documentary heritage institutions".