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.
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."
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.
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?
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
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."