Hey Frappsters!
I’m making this app for the Garments Industry and getting to the point that I need to start thinking about documentation. At first I spun up a site on FrappeCloud and installed Frappe Wiki on it. Managed to create Documentations but quickly realized how difficult it would be to keep them all looking with similar formatting not to include how tedious it would be to update on each feature improvement. Nothing against wiki’s personally but its not the best solution for documentation. So then I found GitBook and it has an interesting concept, create a folder in your project directory called docs, and throw a bunch of markdown files, GitBook will read them sync and show them on their website.
Markdown is fantastic as it eliminates the formatting issue I discussed. And since the documentation lies in my project structure I can even use AI to update the documentation on each feature update. Which simplifies the workload.
Then I went ahead and updated each doctype to link to the external documentation only to realize that in V16 this feature seams to have been ignored and doesn’t show (as in 15 it was working).
Ok so by this point, i’m like WTF. Then it hit me … since the documentation is residing on my project, why don’t i just show the user the documentation as a popup?
This popup opens up whenever the current doctype has a documentation in the folder. It opens by clicking a (?) button placed next to the print and heart on each doctype.
Features:
- Auto Detect your Doctype and open on that documentation
- Full text search
- Option to view as Tree or Focus (Drill-down)
- Full Screen View
- Side Screen View (great for following along with steps, so you can work on the doctype as you read)
- Minimize View (get it out of the way but still present).
- Keeps on page even during Navigation.
- Ability to Increase or Decrease Font Sizes.
- Light and Dark modes matching your theme.
Here is the Side Screen View, allowing users to follow instructions as they are actively working on the site.
Benefits??
The biggest one I can think of, Frappe and ERPNext’s documentation is not great. But its hard for it to be great when updates are coming multiples times a week. You can complain about it, but honestly I tried to maintain documentation but its horrible especially when things are changing so often. Within weeks the code and documentations stop matching up.
But some of the benefits I found when doing it like this:
- The Version of Documentation is consistent with the version installed. Imagine someone is stuck on version 15, but all online documentation’s have been updated to V16. When the documentation resides in your project … your documentation is always up to date with whatever version you are on.
- You can program AI to update the documentation which each feature upgrade, making it easy to keep updated docs even when things are changing quickly.
- Its totally localizable (instead of relying on translations via db or csv files) because you root folder inside docs is your language selector. docs/en for english, docs/es for spanish, etc.
- This structure is then easy to integrate with third party software like GitBook or create Frappe’s very own Documentation library in the future as reading MD files is a no brainer. Plus it will help with SEO and future AI learning as the documentation is not db reliant. So in the future AI can get trained on your app and help users navigate and do things.
WHY am I showing you this???
Here is my proposal. If there is interest from the community and frappe team as well. I can fork and push an update on Frappe to include this as a default feature. We can design it so that whatever app its on, lets say ERPNext, HRMS, CRM, or any of the other 1000s of projects in frappeverse the doctype is always registered to an App.
- Each App can have its own documentation and we can seamlessly show it through one UI.
- This folder structure is generic and can be integrated to many third party apps.
- ERPNext can finally have a Documentation that is worthy of the product.
But I really need to know if this is something frappe wants, as I’m not a fan of doing this and getting rejected down the line. So @rmehta and @sohamkulkarni looking at both of you.
Looking towards the future, we can make the doc interactive by actively hooking actions and showing the user what to do next. Like a checkbox or wizard. Sky’s the limit. Let me know what you think or ideas to make it better. Regardless of interest from the community, this is something i’ve already implemented in my app. In my opinion it looks great and helps end users (non techy end users).
