Documentation Framework

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

1. Protect consumers' time and effort by providing accurate and succinct documentation
2. Create an inviting and efficient new user experience.
3. Identify solutions to common problems
4. Attract new users to the project
5. 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:

1. Developer
2. Integrator/Implementor
3. Development operations (Devops)
4. Translator
5. Tester
6. End-user project manager
7. End-user manager
8. 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.
  • CandidateForObsoleteNotice
  • CandidateForDeletion
  • NeedsToBeUpdated
  • Updated2022
• 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.