Writing an article
Basically, every user and developer of UP is encouraged to write articles in this space. We want a place where application knowledge is concentrated and where application variations are discussed.
To ensure that a certain style is maintained, the rough structure is set out in this read-me. There are also templates for the articles that should be used when creating an article.
Differentiation of the articles
A distinction is made here between two different types of articles:
How-To
A how-to article is instructional and task-oriented. Its primary goal is to guide the reader through the steps required to complete a specific action or set of actions.
It focuses on providing a clear, step-by-step process to achieve a specific outcome.
Best Practice
A best practice article is advisory, focusing on recommending strategies, techniques, or approaches that are considered optimal according to industry standards or expert consensus.
It aims to enhance efficiency, quality, and outcomes in a given area, often based on broader experiences or accepted norms.
How-To Article
Title
Descriptive and Action-Oriented: Clearly state what the user will learn to do. For example, "How to Configure a Parent-Child relation in UP".
Introduction
Purpose: Briefly introduce the task or process that will be explained. Describe the final outcome or what the software will accomplish by following the steps.
Target Audience: Specify who will most benefit from this tutorial (e.g., beginners, advanced users).
Prerequisites
Requirements: List any necessary skills, prior knowledge, or resources the reader should have before starting. Include software versions, necessary permissions, or any initial setup steps.
Step-by-Step Instructions
Sequential Steps: Clearly lay out the steps needed to complete the task. Use numbered lists to guide the reader through the process.
Step Detail: Explain each step thoroughly. Where relevant, explain why the step is necessary as well as how to perform it.
Screenshots or Diagrams: Incorporate visual aids to help illustrate more complex steps or to show exactly what the user should see on their screen.
Code Snippets: If the task involves coding or script entry, provide the exact code needed, explaining any parts that need to be customized.
Tips and Additional Resources
Additional Guidance: Offer tips to enhance understanding or provide shortcuts. Address any common mistakes and how to avoid them.
Links to UP doc: Add appropriate references to the UP-Doc website (e.g. objects/classes used).
Troubleshooting
Common Issues: List typical problems that could occur during the process and provide solutions. This helps preempt user frustration and potential roadblocks.
Verification
Confirm Success: Explain how the reader can confirm that they have successfully completed the task. This could be what the software should display or how it should behave.
Conclusion
Summary: Recap what has been done and the benefits of the configurations or settings adjusted.
Further Applications: Suggest further tweaks or related tasks that can now be performed with the newly acquired knowledge.
Call to Action
Engage Further: Encourage readers to comment with their results, ask questions, or suggest other how-to topics. If there are related tutorials, link to them.
Best Practice Article
Title
Descriptive and Specific: Clearly indicate the practice or feature discussed. Use specific terms that are likely to be searched for.
Introduction
Objective: Briefly state what practice will be discussed and its relevance to the users of the software.
Context: Provide a little background on why this practice is considered a best practice.
Importance of the Practice
Benefits: Outline the benefits of following this best practice.
Potential Pitfalls: Highlight common mistakes or misconceptions associated with not following the best practice.
Detailed Guidelines
Step-by-Step Instructions: Give a clear, concise description of how to implement the best practice. Use bullet points or numbered lists for clarity.
Specific Settings or Commands: Include any necessary technical details like specific settings, configurations, or command lines.
Screenshots or Code Snippets: Provide visual aids or examples to help clarify more complex steps or instructions.
Real-World Application
Example: Provide a practical example that illustrates the successful application of the best practice.
Comparison: Optionally, show a before and after scenario that demonstrates the impact of adopting this practice.
Tips and Additional Resources
Supplementary Tips: Offer additional tips that can help users implement the best practice more effectively.
Further Reading: Link to or suggest further reading materials, official documentation, or tutorials for deeper understanding.
Links to UP doc: Add appropriate references to the UP-Doc website (e.g. objects/classes used).
Conclusion
Recap: Summarize the key points covered.
Encouragement: Encourage the reader to integrate this practice into their regular usage of the software.
Call to Action
Engage Further: Encourage readers to comment with their results, ask questions, or suggest other how-to topics. If there are related tutorials, link to them.
Add Comment