#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".
AMD Working To Release MES Documentation & Source Code
"[..], AMD now says they will be releasing documentation followed by the source code for their Micro-Engine Scheduler (MES) IP block found within Radeon GPUs."
You can add a bit of JavaScript to automatically activate the relevant tab based on the reader's operating system, so they see the relevant info sooner.
I understand why writing good #Documentation is hard. The writer has to both be an expert in the #software , while also imagining they know nothing about it.
Delighted to be able to publicise a paper that was presented at the @ALTAnlp 2023 Workshop at the end of last year, co-authored with my #PhD supervisor, Associate Professor @eltwilliams, and written as part of my research at #ANU School of Cybernetics.
Titled "Right the docs: Characterising voice dataset documentation practices used in machine learning", it combines both exploratory interviews and documentation analysis to characterise how large voice datasets - e.g. #LibriSpeech, @mozilla's #CommonVoice, and several others, document their #metadata.
Unsurprisingly, it finds that the #dataset#documentation practices seen currently do not meet the needs of the #ML practitioners who use these datasets.
We show, once again, in the words of Nithya Sambasivan - "everyone wants to do the model work, but nobody wants to do the data work" ...
Reid, K., Williams, E.T., 2023. Right the docs: Characterising voice dataset documentation practices used in machine learning, in: Muresan, S., Chen, V., Casey, K., David, V., Nina, D., Koji, I., Erik, E., Stefan, U. (Eds.), Proceedings of the 21st Annual Workshop of the Australasian Language Technology Association. Association for Computational Linguistics, Melbourne, Australia, pp. 51–66.
📗 The dated Lucida Grande was the Mac system font a decade ago and used for the docs on Mac (and only Mac). We now use the system font stack, to get a similar result to Linux, Windows, Android and iOS. https://systemfontstack.com
To make them more visible, we've added coloured sidebars and text to the "New in version x.y" / "Changed in version x.y" / " Deprecated since version x.y" directives.
I really hate the trend that #documentation is no longer written but the details are in video #tutorials, especially in #gamedev. I want to READ documentation, with graphics and explanation. On long pages with varying degrees of details. Not some obscure 50min video where I can find the missing piece of information in a single frame at minute 34. #unreal#ue5
PSA: To give me at least a little bit of insight, I've started using the open source, privacy-friendly and non-tracking http://goatcounter.com/ for all important thi.ng related sites/materials, incl. examples & API docs... This will allow me to see which parts are frequented most and help me to (re)focus attention.
Related, the attached heatmap[1] of 6+ years of commits to the https://thi.ng/umbrella monorepo (8480 filtered commits, split by sub-project (rows)) shows that documentation, example projects and build infrastructure have been the most regularly maintained/updated parts throughout all these years. But the project is so vast that many docs still have miles to go to improve, but time is precious and the counter will help me to identify potential weak points (and vice versa)...