Suche
Beiträge, die mit documentation getaggt sind
Just sharing some #history of #Palestine. I've spent the last 15 months learning about Palestine and collecting #historical items and #documentation just in case.
“Don’t cover all the details of the product and the technologies it relies on because no one reads the documentation anyway, right?”
WRONG! If you’re writing for the Web, you can never be sure of the level of computer literacy of the person who has to read your docs. Moreover, you can never know if that person is looking for detailed instructions on how to use a particular feature or API endpoint. Who knows? It might just be something that you or the rest of the team overlooked as secondary.
When it comes to online content, every page is page one. If you want the user to trust you and use your product with confidence, you should strive to provide as much context as possible. For example, if the user is expected to know how to use Node.js and Docker before getting started with a particular CLI-based application, you should explicitly say so at the beginning of the application's tutorial. Ideally, you should not only provide resources for the user to familiarize themselves with these tools, but also explain elsewhere the benefits of using these tools for this application rather than another tech stack.
A documentation site is a highway with no predefined entrances and exits. Any user can start reading it from any point. It's up to you, the content designer, to determine where it logically starts and ends in terms of information architecture, and to make sure there are enough accessible connections to other learning resources along the way.
The learning experience provided to the end user should be analogous to a great technical book like The Unix and Linux System Administration Handbook (1500 pages), which is not only a classic reference, but also a comprehensive resource with a detailed table of contents and index. Although it's regularly updated with new technical advances that have been introduced since the last edition, it still contains the same core.
https://books.google.pt/books?id=f7M1DwAAQBAJ
#TechnicalWriting #SoftwareDocumentation #Documentation #TechnicalCommunication
WRONG! If you’re writing for the Web, you can never be sure of the level of computer literacy of the person who has to read your docs. Moreover, you can never know if that person is looking for detailed instructions on how to use a particular feature or API endpoint. Who knows? It might just be something that you or the rest of the team overlooked as secondary.
When it comes to online content, every page is page one. If you want the user to trust you and use your product with confidence, you should strive to provide as much context as possible. For example, if the user is expected to know how to use Node.js and Docker before getting started with a particular CLI-based application, you should explicitly say so at the beginning of the application's tutorial. Ideally, you should not only provide resources for the user to familiarize themselves with these tools, but also explain elsewhere the benefits of using these tools for this application rather than another tech stack.
A documentation site is a highway with no predefined entrances and exits. Any user can start reading it from any point. It's up to you, the content designer, to determine where it logically starts and ends in terms of information architecture, and to make sure there are enough accessible connections to other learning resources along the way.
The learning experience provided to the end user should be analogous to a great technical book like The Unix and Linux System Administration Handbook (1500 pages), which is not only a classic reference, but also a comprehensive resource with a detailed table of contents and index. Although it's regularly updated with new technical advances that have been introduced since the last edition, it still contains the same core.
https://books.google.pt/books?id=f7M1DwAAQBAJ
#TechnicalWriting #SoftwareDocumentation #Documentation #TechnicalCommunication
UNIX and Linux System Administration Handbook
“As an author, editor, and publisher, I never paid much attention to the competition—except in a few cases. This is one of those cases. The UNIX System Administration Handbook is one of the few books we ever measured ourselves against.Google Books
"4. You’re not just a writer, you’re an advocate for clarity
I thought being a technical writer meant simply explaining what someone else built. But it’s so much more than that. You’re there to simplify complexity, anticipate user needs, and advocate for clarity.
Why it’s key: A good writer doesn’t just document systems, they improve them. In most cases, you should be the first real user of a new feature. Your fresh perspective can highlight gaps and improve the overall experience."
https://bufferbuffer.com/10-things-i-learned-the-hard-way-about-technical-writing-in-tech/
#TechnicalWriting #SoftwareDocumentation #Documentation #Docs #SoftwareDevelopment
I thought being a technical writer meant simply explaining what someone else built. But it’s so much more than that. You’re there to simplify complexity, anticipate user needs, and advocate for clarity.
Why it’s key: A good writer doesn’t just document systems, they improve them. In most cases, you should be the first real user of a new feature. Your fresh perspective can highlight gaps and improve the overall experience."
https://bufferbuffer.com/10-things-i-learned-the-hard-way-about-technical-writing-in-tech/
#TechnicalWriting #SoftwareDocumentation #Documentation #Docs #SoftwareDevelopment
"[T]o build effective docs you not only need tools and content types, but also a model of needs that documentation must satisfy as a product, or of actions users need to accomplish through docs. This model should be fairly independent from the type of software product you’re documenting, in the same way conceptual models of product design and satisfaction abstract away the specifics. Aiming for a general model is necessary because it helps professionals learn and communicate together.
What follows is my own descriptive model of user needs for documentation, one I’m following to build and arrange documentation today.
The approach I’m proposing here is a model of what user actions the docs are meant to satisfy. The model aims at connecting both UX research and documentation frameworks with a conceptual and functional layer that focuses on two aspects: docs as a product and what users are meant to accomplish through them. It’s an attempt at describing what technical documentation should do. It’s treating docs as a product that someone is going to use to achieve actual goals.
As I said, the core of the model is actions. I’ve identified seven that I think cover a decent amount of goals that a consumer of docs may want to accomplish when using documentation. They represent common patterns in how users interact with documentation across different products and domains. They’re the following, each bearing an alternative term in parentheses: Appraise (Discern), Understand (Learn), Explore (Discover), Practice (Train), Remember (Recall), Develop (Integrate), and Troubleshoot (Solve)."
https://passo.uno/seven-action-model/
#TechnicalWriting #Documentation #TechnicalCommunication #UX #DocumentationFrameworks #UXResearch #DocsAsProduct
What follows is my own descriptive model of user needs for documentation, one I’m following to build and arrange documentation today.
The approach I’m proposing here is a model of what user actions the docs are meant to satisfy. The model aims at connecting both UX research and documentation frameworks with a conceptual and functional layer that focuses on two aspects: docs as a product and what users are meant to accomplish through them. It’s an attempt at describing what technical documentation should do. It’s treating docs as a product that someone is going to use to achieve actual goals.
As I said, the core of the model is actions. I’ve identified seven that I think cover a decent amount of goals that a consumer of docs may want to accomplish when using documentation. They represent common patterns in how users interact with documentation across different products and domains. They’re the following, each bearing an alternative term in parentheses: Appraise (Discern), Understand (Learn), Explore (Discover), Practice (Train), Remember (Recall), Develop (Integrate), and Troubleshoot (Solve)."
https://passo.uno/seven-action-model/
#TechnicalWriting #Documentation #TechnicalCommunication #UX #DocumentationFrameworks #UXResearch #DocsAsProduct
The Seven-Action Documentation model
I think all technical writers, at some point or another, feel the urge to base their work on something more systematic than “it’s just the way folks documented stuff since forever”.passo.uno
#israel #palestine : #war / #gaza / #literature / #eyewitness / #documentation / #counterpublic
„Mahmoud Muna is the owner of the Educational Bookshop in East Jerusalem and one of the editors of “Daybreak in Gaza: Stories of Palestinian Lives and Cultures”. The book collects testimonies and stories from over a hundred Gazans, documenting their lives before and during Israel’s ongoing war on the enclave.”
https://qantara.de/en/article/mahmoud-muna-editor-daybreak-gaza-book-about-hope-anger-and-anguish
„Mahmoud Muna is the owner of the Educational Bookshop in East Jerusalem and one of the editors of “Daybreak in Gaza: Stories of Palestinian Lives and Cultures”. The book collects testimonies and stories from over a hundred Gazans, documenting their lives before and during Israel’s ongoing war on the enclave.”
https://qantara.de/en/article/mahmoud-muna-editor-daybreak-gaza-book-about-hope-anger-and-anguish
➡️ The PHP manual has learned a new trick, you can now run the code right in the browser!
🥳 Thanks to @soyuka for the implementation!
#php #documentation
🥳 Thanks to @soyuka for the implementation!
#php #documentation
#Gaza #documentation
Why is our website different to other existing websites?
You can read the answer in the third tab on this page: https://pares.glosm.eu/index.php
Why is our website different to other existing websites?
You can read the answer in the third tab on this page: https://pares.glosm.eu/index.php
Welcome page
GLOSM/PARES is a documentation website mainly focusing on the "war" in Gaza but in the context of international law. However, the website includes also the documentation regarding effects the "war" is causing, in particular in Western countries.GLOSM/PARES
#Gaza #documentation
We're slowly bringing the whole archive but in backwards order online as November 2024 is nearly complete online; October 2024 & #October7th, are complete online. Now preparing: Sept. 2024.
https://pares.glosm.eu/index.php
We're slowly bringing the whole archive but in backwards order online as November 2024 is nearly complete online; October 2024 & #October7th, are complete online. Now preparing: Sept. 2024.
https://pares.glosm.eu/index.php
Welcome page
GLOSM/PARES is a documentation website mainly focusing on the "war" in Gaza but in the context of international law. However, the website includes also the documentation regarding effects the "war" is causing, in particular in Western countries.GLOSM/PARES
#france #israel #palestine : #war / #gaza / #westbank / #opt / #dissent / #openletter / #documentation
„In an article published in 'Le Monde,' leading figures of the Jewish faith and culture denounce the visit to Paris on November 13, of the finance minister for Benjamin Netanyahu's government, who is hostile to a ceasefire in the Israel-Hamas war and defends the illegal settlements in the occupied West Bank: “
https://www.lemonde.fr/en/opinion/article/2024/11/10/war-in-the-middle-east-israeli-minister-bezalel-smotrich-a-supremacist-and-revisionist-should-not-be-welcomed-in-france_6732288_23.html?lmd_medium=al&lmd_campaign=envoye-par-appli&lmd_creation=ios&lmd_source=default
„In an article published in 'Le Monde,' leading figures of the Jewish faith and culture denounce the visit to Paris on November 13, of the finance minister for Benjamin Netanyahu's government, who is hostile to a ceasefire in the Israel-Hamas war and defends the illegal settlements in the occupied West Bank: “
https://www.lemonde.fr/en/opinion/article/2024/11/10/war-in-the-middle-east-israeli-minister-bezalel-smotrich-a-supremacist-and-revisionist-should-not-be-welcomed-in-france_6732288_23.html?lmd_medium=al&lmd_campaign=envoye-par-appli&lmd_creation=ios&lmd_source=default
War in the Middle East: 'Israeli minister Bezalel Smotrich, a supremacist and revisionist, should not be welcomed in France'
In an article published in 'Le Monde,' leading figures of the Jewish faith and culture denounce the visit to Paris on November 13, of the finance minister for Benjamin Netanyahu's government, who is hostile to a ceasefire in the Israel-Hamas war and …Group letter (Le Monde)