Suche
Beiträge, die mit technicalcommunication getaggt sind
"When evaluating documentation’s role, consider these broader strategic questions:
- Strategic positioning: How does documentation support the company’s core strategic approach?
- Competitive advantage: Can documentation create or enhance the company’s unique market position? What type of documentation does the competition offer?
- Value proposition: How does documentation contribute to the product’s overall value for customers?
- Knowledge management: How does documentation support internal knowledge retention and transfer?
- Customer lifecycle: How can documentation improve customer acquisition, retention, and satisfaction?"
https://www.thegooddocsproject.dev/blog/making-business-base-know-company-goals
#TechnicalWriting #Documentation #SoftwareDocumentation #TechnicalCommunication
- Strategic positioning: How does documentation support the company’s core strategic approach?
- Competitive advantage: Can documentation create or enhance the company’s unique market position? What type of documentation does the competition offer?
- Value proposition: How does documentation contribute to the product’s overall value for customers?
- Knowledge management: How does documentation support internal knowledge retention and transfer?
- Customer lifecycle: How can documentation improve customer acquisition, retention, and satisfaction?"
https://www.thegooddocsproject.dev/blog/making-business-base-know-company-goals
#TechnicalWriting #Documentation #SoftwareDocumentation #TechnicalCommunication
"When evaluating documentation’s role, consider these broader strategic questions:
- Strategic positioning: How does documentation support the company’s core strategic approach?
- Competitive advantage: Can documentation create or enhance the company’s unique market position? What type of documentation does the competition offer?
- Value proposition: How does documentation contribute to the product’s overall value for customers?
- Knowledge management: How does documentation support internal knowledge retention and transfer?
- Customer lifecycle: How can documentation improve customer acquisition, retention, and satisfaction?"
https://www.thegooddocsproject.dev/blog/making-business-base-know-company-goals
#TechnicalWriting #Documentation #SoftwareDocumentation #TechnicalCommunication
- Strategic positioning: How does documentation support the company’s core strategic approach?
- Competitive advantage: Can documentation create or enhance the company’s unique market position? What type of documentation does the competition offer?
- Value proposition: How does documentation contribute to the product’s overall value for customers?
- Knowledge management: How does documentation support internal knowledge retention and transfer?
- Customer lifecycle: How can documentation improve customer acquisition, retention, and satisfaction?"
https://www.thegooddocsproject.dev/blog/making-business-base-know-company-goals
#TechnicalWriting #Documentation #SoftwareDocumentation #TechnicalCommunication
"The following are my suggestions regarding what else to consider for each of Daryl White’s excellent questions about choosing a toolset for documenting a software product or project.
I have appended a brief guide to the main/broad categories of documentation toolsets and some of the platforms/components that are popular in each.
Finally, this resource ends with a table of possible solutions for various scenarios you might find yourself in.
Before we start with the existing list of questions, I want to highlight one that I think is most important of all, but which is often assumed by people who create these kinds of guides, as they tend to come from one or another world already.
What are you documenting?
When it comes to software technical writing, the more appropriate way to ask this might be: For what user roles is your documentation intended?
For graphical end-user interfaces (GUIs), the largest range of docs tooling is available, but here some of the more commercial turnkey tools have most of their advantages.
For administrator interfaces (installation, configuration, etc), again any tooling will work, but we start seeing real advantages for lightweight markup, codebase integration, and version control.
For developer interfaces, docs-as-code offers significant advantages. Developers can better contribute directly, and it’s generally friendlier for coded samples. APIs (native and remote), SDKs, and CLIs are almost certainly best documented in a docs-as-code environment, even if you integrate it with a more conventional platform for end-user docs."
https://gist.github.com/briandominick/d4cbe11228de0ebe31cda630976af4ef
#TechnicalWriting #SoftwareDocumentation #Documentation #DocsAsCode #TechnicalCommunication #InformationArchitecture #CCMS
I have appended a brief guide to the main/broad categories of documentation toolsets and some of the platforms/components that are popular in each.
Finally, this resource ends with a table of possible solutions for various scenarios you might find yourself in.
Before we start with the existing list of questions, I want to highlight one that I think is most important of all, but which is often assumed by people who create these kinds of guides, as they tend to come from one or another world already.
What are you documenting?
When it comes to software technical writing, the more appropriate way to ask this might be: For what user roles is your documentation intended?
For graphical end-user interfaces (GUIs), the largest range of docs tooling is available, but here some of the more commercial turnkey tools have most of their advantages.
For administrator interfaces (installation, configuration, etc), again any tooling will work, but we start seeing real advantages for lightweight markup, codebase integration, and version control.
For developer interfaces, docs-as-code offers significant advantages. Developers can better contribute directly, and it’s generally friendlier for coded samples. APIs (native and remote), SDKs, and CLIs are almost certainly best documented in a docs-as-code environment, even if you integrate it with a more conventional platform for end-user docs."
https://gist.github.com/briandominick/d4cbe11228de0ebe31cda630976af4ef
#TechnicalWriting #SoftwareDocumentation #Documentation #DocsAsCode #TechnicalCommunication #InformationArchitecture #CCMS
"The accompanying diagram is intended to help you quickly decide how to document an API, but particularly a REST API. The first split is just to make sure you are looking for the right kind of API.
Here is some more context to help you decide on an approach and get started."
https://gist.github.com/briandominick/3ffab6be460fbde799aa34e0a42a4299
#API #APIs #APIDesign #REST #APIDocumentation #OpenAPI #DocsAsCode #TechnicalWriting #TechnicalCommunication
Here is some more context to help you decide on an approach and get started."
https://gist.github.com/briandominick/3ffab6be460fbde799aa34e0a42a4299
#API #APIs #APIDesign #REST #APIDocumentation #OpenAPI #DocsAsCode #TechnicalWriting #TechnicalCommunication
API Documentation Decision Matrix
API Documentation Decision Matrix. GitHub Gist: instantly share code, notes, and snippets.Gist
"Tech comms can be a business, but thinking is not selling: it requires intellectual freedom and courage. Leaving these conversations to engineers risks turning technical communication into a caricature of itself, a four-quadrant fantasy devised to lure developers into thinking that documentation is a simple pastime, yet another Jira task.
Only independent thought can help us progress and navigate uncertainty, including our future in a world where AI is injected into every domain that deals with words. Technical writers must own their problems and the conversations around them, or they will slowly fade into irrelevance, their problems absorbed by other disciplines that have more pressing problems to focus on. And if you’re reading that we should lobby more, you’re not wrong: defending knowledge requires power.”
#TechnicalWriting #TechnicalCommunication #SoftwareDocumentation #CriticalThinking
https://passo.uno/tech-writing-depth-issue/
Only independent thought can help us progress and navigate uncertainty, including our future in a world where AI is injected into every domain that deals with words. Technical writers must own their problems and the conversations around them, or they will slowly fade into irrelevance, their problems absorbed by other disciplines that have more pressing problems to focus on. And if you’re reading that we should lobby more, you’re not wrong: defending knowledge requires power.”
#TechnicalWriting #TechnicalCommunication #SoftwareDocumentation #CriticalThinking
https://passo.uno/tech-writing-depth-issue/
Technical writing has a depth issue
Demoralized by the advent of LLMs, I see tech writing communities break ranks and flee. In a world where coders who write seem to muster more respect than writers who code, the response from tech writers to the challenges posed by the intersection of…passo.uno
“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
"[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