Guide to Writing Product Documentation Articles

Below are the steps to follow for creating product documentation articles for Athento:

1. Adapt the content to the audience.
Who is the article you are writing for?

• If it's a general topic focused on non-technical users, keep this in mind to ensure that the text is understandable and serves its purpose of solving a problem.
• If it's a specific topic focused on technical users, consider using technical jargon and details necessary for that type of user to configure or resolve the issue they are seeking help for.

2. What do you need to write about?
If there are instructions, client inquiries, or requests from team members, carefully read the guidelines to understand what needs to be addressed in the product documentation article you are writing.

3. Propose 2-3 headings summarizing the ideas you want to convey in the article.
Summarize the ideas you want to write about.

Headings that separate different sections of the text not only facilitate writing but also readability of the article.

4. Article layout:

• Introduction: Introduce the main idea, functionality, concept, or frequently asked question that will be explained. 1 paragraph
• Headings: Explain or describe the main ideas. 2 to 3 paragraphs under each heading.
• Article conclusion: If applicable, include a summary, conclusion, or links to additional information.

5. How to write in practice:

• Develop the introduction and headings.
  • Explain or describe the ideas you have outlined in the headings. Use examples to illustrate what you mean whenever possible.
  • Always try to start with the minimal version of the idea and then expand.
  • Always separate the text into paragraphs to facilitate reading.
  • The key to good writing is short sentences that are easy to understand.
• Editing is also writing.
  • Before finalizing the article, go back over your words and look at any errors you may have missed (typing errors, extra words, spelling, etc.).
  • Also, ensure that the text answers the question posed in the article. If it's unclear, make changes. If you've gone on too long, consider dividing the text into several entries in the documentation center.
• Make the text visually appealing.
  • Use bold to highlight keywords or key ideas. Don't overuse them!
  • Use bold in a way that allows readers to read and understand the general idea of the article by only reading the highlighted text.
  • Italics are also an auxiliary element for emphasis that you can use.
  • Include links that you consider facilitate accessing related information about the frequently asked question or functionality being addressed.
  • Include images or videos whenever possible to graphically explain how to perform an action or configuration.

It's important to remember:

• Starting in 2024, make product documentation articles public and indexable by Google.
• Anonymize articles: Remember not to include customer data or cases with customer data in public articles. In cases where the information is incomplete without including sensitive or confidential data, there are two alternatives:
  • Create the article with essential and generic data and include at the end a text: "For more detail, visit the following link: XXX (link to an internally restricted access document). This way, we have at least the basics published so that it can be indexed by search engines, and customer data can only be viewed by registered users.
  • Create two versions of the same article: one with generic information and the other with the details of the customer use case. The latter, with restricted access only to registered users.
  • *Before anonymizing an existing article or making an existing article public internally that contains sensitive data, check if it is appropriate.
• Include tags related to the topic of the article to make it easier for the article to be found in search engines.
• To publish the new content: assign it to the "Novedades en la documentación" category pending review.

Best practices and recommendations:

• Spelling mistakes: We recommend using browsers like Chrome that allow you to spell-check the article in real-time by underlining words with spelling errors in red. You can also paste the text into Word or Google Docs to detect spelling errors, correct them, and then paste the correct text into Zendesk. In any case, make sure not to publish the article with obvious spelling mistakes.
• Translations: Once you finish writing the article, translate it using DeepL, Translate, or ChatGPT and include it in the corresponding tab in Zendesk. Check out the tutorial on how to create articles in Zendesk.
• Use a neutral tone and third person.
• Use verbs in the present tense. They are descriptive and positive. Avoid conditionals and compound futures that add complexity to understanding the text.
• Name the images: Edit the name of the images by including a brief name related to the content of the article followed by '_Athento'. For example: integrationSAP_Athento. If there are several similar images or images explaining the steps of the same procedure, use the same name numbering each image. For example: integrationSAP_Athento, integrationSAP2_Athento, integrationSAP3_Athento. Editing the name of the images is essential for SEO positioning, as it allows our content to be positioned in Google's image search engine or appear as a search result if there is no text content that answers the user's query.
• Include boxes, arrows, or marks in the images to guide the user in understanding the commands they need to follow or where the buttons or information to consult are located.
• Try to make it easy, start with the minimum version of content you can prepare to break the barrier of the blank page and complete the article gradually.
• Do it today and don't leave it for tomorrow.

Security Recommendations

• In screenshots or videos, hide browser bookmarks or other tabs, or edit the screenshot/video to remove bookmark and tab information that that could lead to security attacks.
• In screenshots or videos, hide URLs as much as possible to avoid revealing which internal tools we use (which can also be a clue for information security attacks).
• To easily hide the Chrome bookmarks bar: Ctrl+Shift+B (on Windows).