Difference between revisions of "Documentation Framework"
From iDempiere en
(→Who Served: - added section) Tag: visualeditor |
m Tag: visualeditor |
||
| (19 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
==Purpose== | ==Purpose== | ||
| − | The purpose of this page is to describe the iDempiere documentation | + | The purpose of this page is to describe the iDempiere documentation framework. 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. |
| − | == Who | + | == Planning and Organization == |
| − | There are many actors in creating, maintaining and consuming | + | The Documentation Committee meets weekly using [https://mattermost.idempiere.org/idempiere/channels/documentation mattermost] using the Documentation Channel. Anyone is welcome to join and contribute. [[Documentation Discussion|We organize thoughts and initiatives here]]. |
| + | |||
| + | ==Goals and Objectives== | ||
| + | "''Many hands make for little work''" is a core principle of the group. We believe that everyone can contribute to documentation in one way or another. | ||
| + | |||
| + | Our primary objectives are to: | ||
| + | |||
| + | # Choose and support the the right tools to make it easy for everyone to contribute. | ||
| + | # Educate and incentivize everyone's involvement. | ||
| + | |||
| + | If we execute our objectives, we believe the following goals will be achieved: | ||
| + | *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 | ||
| + | |||
| + | These goals and objective should create easily accessible, simple, consistent and accurate documentation. | ||
| + | |||
| + | == Who We Serve == | ||
| + | There are many actors in creating, maintaining and consuming documentation. Here are the identified documentation consumers: | ||
# Developer | # Developer | ||
| Line 10: | Line 30: | ||
# Translator | # Translator | ||
# Tester | # Tester | ||
| + | # Trainer | ||
# End-user project manager | # End-user project manager | ||
# End-user manager | # End-user manager | ||
# End-user user | # End-user user | ||
| − | + | These same actors are ones who also create the documentation. Any actor can be a newcomer or a veteran. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
==Models and Standards== | ==Models and Standards== | ||
| − | [https://diataxis.fr/ Diataxis] | + | We use the [https://diataxis.fr/ Diataxis] framework. Their website is pretty well organized. [https://www.youtube.com/watch?v=t4vKPhjcMZg&t=327s Quick summary video.] |
| − | *Categories | + | *Categories of documents |
**'''[[:Category:Tutorial|Tutorial]] (Learning-oriented)''': lessons that take the reader by the hand and provide a series of predefined steps to accomplish a goal. | **'''[[:Category:Tutorial|Tutorial]] (Learning-oriented)''': lessons that take the reader by the hand and provide a series of predefined steps to accomplish a goal. | ||
**'''[[:Category:HowTo|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. | **'''[[:Category:HowTo|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. | ||
**'''[[:Category:Explanation|Explanation]] (Understanding-oriented):''' discussion that clarifies and illuminates a particular topic. | **'''[[:Category:Explanation|Explanation]] (Understanding-oriented):''' discussion that clarifies and illuminates a particular topic. | ||
| − | **'''[[:Category:Reference|Reference]] (Information-oriented):''' technical descriptions of the machinery and how to operate it. | + | **[[Category:Developer documentation|Developer Documentation]] '''[[:Category:Reference|Reference]] (Information-oriented):''' technical descriptions of the machinery and how to operate it. |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
==Getting Started - Cleaning the wiki== | ==Getting Started - Cleaning the wiki== | ||
| Line 40: | Line 48: | ||
*Sign up for an account in the wiki if you don’t have one: [[Special:RequestAccount|Request Account]] | *Sign up for an account in the wiki if you don’t have one: [[Special:RequestAccount|Request Account]] | ||
*Review [https://wiki.idempiere.org/en/Documentation_Framework#Models_and_Standards standards and examples]. | *Review [https://wiki.idempiere.org/en/Documentation_Framework#Models_and_Standards standards and examples]. | ||
| − | *Consider posting your idea/thought on the google group | + | *Consider posting your idea/thought on [https://mattermost.idempiere.org/idempiere/channels/documentation Mattermost] (preferred) and/or the [https://groups.google.com/g/idempiere iDempiere google group]. 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. | *Use the wiki discussion page to formulate and aggregate your thoughts. | ||
*Click on Edit and add the corresponding tag to the page. | *Click on Edit and add the corresponding tag to the page. | ||
| Line 47: | Line 55: | ||
**[[:Category:NeedsToBeUpdated|NeedsToBeUpdated]] | **[[:Category:NeedsToBeUpdated|NeedsToBeUpdated]] | ||
**[[:Category:Updated2022|Updated2022]] | **[[:Category:Updated2022|Updated2022]] | ||
| − | |||
| − | |||
| − | |||
| − | == | + | == Documentation Links and Resources == |
| − | + | *Wiki [[Special:Statistics|documentation statistics]] | |
| − | + | *[https://www.idempiere.org/contributors/ Project Contributors] | |
| − | * | + | *Book: [https://www.packtpub.com/product/adempiere-34-erp-solutions/9781847197269 ADempiere 3.4 ERP Solutions] |
| − | * | ||
| − | * | ||
| − | |||
[[Category:Documentation]] | [[Category:Documentation]] | ||
[[Category:Updated2022]] | [[Category:Updated2022]] | ||
Latest revision as of 23:35, 18 May 2023
Purpose
The purpose of this page is to describe the iDempiere documentation framework. 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.
Planning and Organization
The Documentation Committee meets weekly using mattermost using the Documentation Channel. Anyone is welcome to join and contribute. We organize thoughts and initiatives here.
Goals and Objectives
"Many hands make for little work" is a core principle of the group. We believe that everyone can contribute to documentation in one way or another.
Our primary objectives are to:
- Choose and support the the right tools to make it easy for everyone to contribute.
- Educate and incentivize everyone's involvement.
If we execute our objectives, we believe the following goals will be achieved:
- 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
These goals and objective should create easily accessible, simple, consistent and accurate documentation.
Who We Serve
There are many actors in creating, maintaining and consuming documentation. Here are the identified documentation consumers:
- Developer
- Integrator/Implementor
- Development operations (Devops)
- Translator
- Tester
- Trainer
- End-user project manager
- End-user manager
- End-user user
These same actors are ones who also create the documentation. Any actor can be a newcomer or a veteran.
Models and Standards
We use the Diataxis framework. Their website is pretty well organized. Quick summary video.
- Categories of documents
- 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.
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 Mattermost (preferred) and/or the iDempiere google group. 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.
