Documentation Discussion

Purpose

The purpose of this page is to support Documentation Committee planning.

What we should ask Ourselves Often

• What attracts the best and most developers?
• What drives contribution to the project?

Prioritized Future Agenda Items

1. Continue tool selection
   1. what role does new tool play (deprecate wiki)?
2. Review @hengsin example documentation - how to promote more contributions and organize?
3. Update on current cleaning initiative
4. Giving initial credit to those who start a document and ongoing credit to those who contribute
5. Maintaining multiple medium criteria (wiki + pdf)
6. Identify common tasks (write plugins, create test cases, create user documentation, contribute to the core, etc..)
7. Identify and support common iDempiere business use cases (distribution, professional services, manufacturing, etc...)
8. Where do we want code examples to live (examples of each of the plugin interfaces - process, callout, model event, etc...)
9. Measurable proxies for success
10. Copyright issues (general and on raw documentation parts provided by contributors)

Current Initiatives

1. Docusaurus go-live with next version of iDempiere
2. Wiki Cleaning Initiative (priority for developers and project contribution)
3. Tool Selection (priority for developers and project contribution)
4. Window Documentation

Docusaurus go-live

Open items:

• movement to a docs.idempiere.org domain
• Installation completion
• Functional Basics completion
• Development Basics completion

Tool Selection

Choosing the right documentation tools for the right audience goes a long way to getting everyone involved and achieving our goals.

Tools Proposed (in no order):

• wiki (media-wiki - current)
• readthedocs.org
  • suggested by @ralexsander
  • contributor get github cred/stats (big motivator for some)
• docusaurus.io
  • suggest by @anozimada
  • POC: https://idempiere-id.github.io/
  • Discussion: https://mattermost.idempiere.org/idempiere/pl/dnspfybe1j8t9yjjbc9mx6feoo
    • and https://mattermost.idempiere.org/idempiere/pl/bp6sx6y5hirjbkyib8yxibwq7y
  • giscus - comments for published pages
• jekyll
  • suggested by @hengsin
  • Static site generator
  • github will auto deploy upon commit
• jamstack
  • suggest by @anozimada
  • concerns (as stated by @anozimada): markdown and pull request workflow
• gitbook
  • suggested by @pedrorozo

Tool Considerations

Below were the mentioned decision considerations (in no order):

• translation
• versioning
• ability to create iDempiere manual (W,T & F documentation)
• github cred/stats
• integration with github
• easy to use (preferably well known) by the intended contributors (example: markdown)
• ability to generate PDFs
• search-ability (index-ability)
• navigation friendly
• seo friendly
• ability to use existing documentation and rebrand for customer use
• ability to clone for use (examples)
• account management (how manage accounts to control spam or corruption of content. so who will granted access is important.)
• comments

Tool Role

There is a need for improved documentation tools. What role does the new tool provide? Does it completely replace the current wiki?

Valuable comments:

• Carlos
  • I don't understand that we're choosing docusaurus and deprecate the wiki - they have different goals
  • mediawiki is highly collaborative - easy to contribute (just edit and you're ready)
  • docusaurus is more organized - more difficult to contribute (pull request workflow probably) and they have different goals
  • for me docusaurus is perfect for the manuals - but mediawiki can be good for other purposes the available plugins - the new features pages
  • we also need to think what will happen when we have the two tools running aside - if somebody creates content in the wiki that must go to docusaurus

Cleaning Initiative

The goal is to update or eliminate hazardous material using the wiki's tags as follows:

• 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)

Window Documentation

• Notes about project
  • Window Documentation is a must, but targets end users more than developers.
• We believe that the 'quality of window documentation' is an important enough issue to warrant a solution
• Update project pull request guidelines to include meaningful application dictionary text
• Consider having a dedicated iDempiere instance up and running to support W,T&F / T&C application dictionary changes
• Users would log into GardenWorld and propose changes using existing system
• Admin would approve changes
• Documentation team to create automation to commit changes to core project
• Admin to determine if guest account is allowed. Pro: possible more feedback, Con: possible more contamination
• Demonstration

Past Agenda Items

• How to improve - how to contribute to the dictionary documentation and translations
• Status of fitnesse documentation update
• Docusaurus - current status of evaluation (see tool considerations)
• Page + comments/discussion = best practice?
• Issue with edit in wiki (captcha not let pass)
• Continue tools discussion
• Plans around current wiki cleaning initiative
• Review artifacts and get feedback
• Continue tools discussion
• Community engagement plan/calendar