Difference between revisions of "Documentation Framework"
From iDempiere en
(→Who Served: - added section) Tag: visualeditor |
m Tag: visualeditor-switched |
||
| Line 1: | Line 1: | ||
==Purpose== | ==Purpose== | ||
The purpose of this page is to describe the iDempiere documentation standard. This page should help you update existing material and create new material in a way that is consistent with the success of the iDempiere project. | The purpose of this page is to describe the iDempiere documentation standard. This page should help you update existing material and create new material in a way that is consistent with the success of the iDempiere project. | ||
| + | |||
| + | ==Goals== | ||
| + | #Protect consumers' time and effort by providing accurate and succinct documentation | ||
| + | #Create an inviting and efficient new user experience. | ||
| + | #Identify solutions to common problems | ||
| + | #Attract new users to the project | ||
| + | #Flag material that might degrade the user experience | ||
== Who Served == | == Who Served == | ||
| Line 14: | Line 21: | ||
# End-user user | # End-user user | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
==Models and Standards== | ==Models and Standards== | ||
Revision as of 20:30, 28 March 2023
Purpose
The purpose of this page is to describe the iDempiere documentation standard. This page should help you update existing material and create new material in a way that is consistent with the success of the iDempiere project.
Goals
- Protect consumers' time and effort by providing accurate and succinct documentation
- Create an inviting and efficient new user experience.
- Identify solutions to common problems
- Attract new users to the project
- Flag material that might degrade the user experience
Who Served
There are many actors in creating, maintaining and consuming documents. Here are the identified documentation consumers:
- Developer
- Integrator/Implementor
- Development operations (Devops)
- Translator
- Tester
- End-user project manager
- End-user manager
- End-user user
Models and Standards
Diataxis is the the proposed framework. Their website is pretty well organized. Quick summary video.
- Categories
- Tutorial (Learning-oriented): lessons that take the reader by the hand and provide a series of predefined steps to accomplish a goal.
- How-To (Task-oriented): directions that take the reader through the steps required to solve a real-world problem, these are intended for people that already know how to use iDempiere.
- Explanation (Understanding-oriented): discussion that clarifies and illuminates a particular topic.
- Reference (Information-oriented): technical descriptions of the machinery and how to operate it.
- Hazardous Material - used to identify problematic pages
- First pages to clean/purge: Category:Developer documentation
- Use these tags for the cleaning process:
- CandidateForObsoleteNotice
- CandidateForDeletion
- NeedsToBeUpdated
- Updated2022 (To let others know you reviewed the page and everything is up to date)
Getting Started - Cleaning the wiki
Did you find a page that could be improved, needs an update or should be removed? Please help us discover these pages by following these steps:
- Sign up for an account in the wiki if you don’t have one: Request Account
- Review standards and examples.
- Consider posting your idea/thought on the google group and/or Mattermost. This helps ensure you understand what is currently available related to your change, and it invites the community to help support your efforts.
- Use the wiki discussion page to formulate and aggregate your thoughts.
- Click on Edit and add the corresponding tag to the page.
- Additionally, you can let us know on Mattermost which page needs attention on the Documentation channel.
Search on key work to find similar pages (example: install)
Getting Started - Creating your First Page
This section assumes you have an idea to create new content. These are the first steps to help you make your idea a reality.
- Sign up for an account in the wiki if you don’t have one: Request Account
- Review standards and examples.
- Post your idea/thought on the google group and/or Mattermost. This helps ensure you understand what is currently available related to your change, and it invites the community to help support your efforts.
- Use the wiki discussion page to formulate and aggregate your thoughts.
