How to contribute to frappe documentation?

Frappe Framework
1

Hello Beautiful peopl,

So the frappe documentation is… bad.
How it’s possible to contribute to it?

David

1 Like
2
  1. Got to Frappe Framework : Introduction
  2. Scroll to the bottom of the page
  3. Click on Improve this page
  4. Clone the frappe_io repository you’ll find there.
  5. Make your edits
  6. Submit a PR
1 Like
3

Thanks…
I should probably PR this to the docs as well XD

Anyway, the docs should really be merged with the frappe framework, so that the documentation changes in PR are easier to manage.

4

I am believer in very tight binding between code and documentation using annotations, but retro-fitting is usually impossible. If you haven’t started that way, it isn’t worth fighting the war you’d have to wage to get everyone on board with doing it properly.

5

Could be done in 15 minutes like this:

  1. Move folder from frappe.io repo to frappe repo with two PR
  2. Set up CI to that frappe repo is cloned during CI build and directory is copied where it should be
  3. Set up cron to trigger CI build daily

I might do it I’m constantly pissed off by the developers blatant disregard for documentation. At least if they are in the same repo they’re going to be more incentivised to incorporate it in the same PRs and make everything look tidy.

6

You misunderstand me.

Checkout this 4 min video (2 mins if you 2x the speed) Auto-Generated Python Documentation with Sphinx

Now I realise that that is deep developer documentation; I only use it to illustrate my point.

Check out this DocType documentation section for Item: Deferred Revenue>> 1. How to use Deferred Revenue

Here’s the relevant DocType code section:

Now imagine if it looked like this:

{
 "default": "0",
 "fieldname": "enable_deferred_revenue",
 "fieldtype": "Check",
 "label": "Enable Deferred Revenue"
   "bubble": {
      "en": "You can enable deferred revenue or expense from the item. Once you tick the checkbox, you'll see options to set the Deferred Expense Account and the number of months through which the revenue/expense is deferred.",
      "es": "Puede habilitar los ingresos o gastos diferidos del artículo. Una vez que marque la casilla de verificación, verá las opciones para configurar la Cuenta de gastos diferidos y la cantidad de meses a través de los cuales se difieren los ingresos / gastos.",
      "fr": "Vous pouvez activer des revenus ou des dépenses différés à partir de l'article. Une fois que vous avez coché la case, vous verrez des options pour définir le compte de dépenses différées et le nombre de mois pendant lesquels les revenus / dépenses sont différés."
    },
    "learn_more": "../../${language}/accounts/deferred-revenue.md"
  },

The file ../../${language}/accounts/deferred-revenue.md would contain the markdown from the text below, but it would be in the same directory hierarchy, not in a different git repository like it is now.
https://github.com/frappe/erpnext_documentation/blob/master/erpnext_documentation/www/docs/user/manual/en/accounts/deferred-revenue.md

See what I mean by “very tight binding between code and documentation”?

Detractors would argue that scattering the documentation all over the place like that would make it unmanageable. Right! That’s why I pointed out the Sphinx video to begin with. Purpose built docs management software to be used by translators, trainers, etc as well as docs developers and code developers would hide the complexity.

As a matter of fact you could have your Cypress tests structured to be part of it. Properly created Cypress tests that popped up the docs at the right moment could be videoed then rendered at slow speed, and an automated reader could add the audio from time stamped explanations generated from the Cypress test. Just-in-time training auto-generated from the code!

1 Like
7

Yes I understand what you mean, this is indeed how it should be, but the frappe developers have long been impervious to these approaches.

No kidding I have known this framework since version 10 and only since January I started really using it, so much time wasted because of incomplete documentation.

There are so many completely undocumented fields and parameters and features. Did you know there is a real time query recorder within frappe? feat: Recorder by adityahase · Pull Request #6952 · frappe/frappe · GitHub who the hell did? I didn’t, it’s not written anywhere.

I am curious, if one where to setup sphinx, if there would be some immediate improvement to the documentation, considering the python code itself is often commented.

1 Like
8

I just checked and there is a ration of code to documentation commits of 50:1, it’s totally outrageous.

We must as the community do something to address this, since it has been going for many years.

1 Like
9

I get you.

Sadly the response seems to be “It’s a DIY project, own the code like you would all the parts of any other do-it-yourselfer and you won’t need documentation” :poop:

Am I wrong or are there not ERPNext consulting companies all around the world charging pots of money to serious customers to install and manage ERPNext company wide?

If there aren’t, then skimpy confusing docs could be a major reason for it.

Otoh, if there are then they’re the ones who ought to be dedicating full-time resources to making the whole learning experience MUCH smoother.

10

They’re all small independent companies.

But even then, almost no-one is building apps on Frappe. Which is a real pity because A LOT of app development in the world in building the kind of apps Frappe is wonderful for.

Can you take a look at GitHub - frappe/frappe_docker: Docker images for production and development setups of the Frappe framework and ERPNext and tell me what do you think?

11

I haven’t used the docker image, It looks like I probably should.

12

I’m now maintainer of the documentation

5 Likes
13

:slight_smile: you get what you deserve hahaha.

I agree and am happy that you voiced a recurring opinion and are taking this role on. I"m also really glad to see the project team take what you said constructively and hand it to you. I like projects that are doocracies rather than sandboxed ego trips. So cheers to everyone!

While I’m not an expert in Frappe, and I read code better than I can write it, I’d like to learn to be, and one way would be to document things. If I can help I would like to.

My degree is in English, not CS, so I"m self-taught and lacking still a lot of programming knowledge and skills. I think participating in writing documentation for others in my same position would help me more to learn if you’re willing to point me in the right directions and put up with the occasional stupid question and maybe some bad jokes.

2 Likes
15

I have noticed that many of the questions here are requests for elaboration on things the docs cover too skimpily. Then the replies are usually untested snippets without enough context to be clear how they should be effected.

When I find the docs don’t provide enough to get what I want, I ask about it in the forum here, then document my search for a solution as a reply to my own question. I make the replies as explanatory as possible and provide tested examples with installation instructions.

Here’s an example: [solved] cURL example of an attachment upload RPC call? - #3 by MartinHBramwell

I wish everyone would do this.

In any case, please feel free to incorporate any such Q & A of mine into the official docs.

3 Likes
16

True for both, but then again, aren’t they the ones who may think they benefit from keeping the hard earned knowledge and experience to themselves? E.g. in order to impress clients and keep competitors, and wannabees, maybe not at bay, but still less knowledgeable than otherwise.

How to resolve such a conflict of interest, or “moral hazard”?

Also, earning the laurels takes a lot of time. The steepness of the learning curve and the bitterness of the patience necessary are well-known to the ecosystem surrounding Frappe from citations on certain documentation intro pages.
Who can blame those who spend their other time applying their knowledge to earn what they need to counterfinance that drag?
Similarly, who can blame Frappe to earn from FrappeCloud after years of building all this, even if the doc is still kind of lacking?

But lacking documentation also hinders the growth of devs everywhere and thus keeps very widespread adoption slow, so having it lag behind still leaves an advantage to others like odoo, dokos, non-FLOSS projects, etc.

So, after all, I guess the best learners, those who understand the quickest with little doc but ample code, clearly have an advantage and will naturally be the fastest, maybe also, after a time, the biggest driver of adoption of the kind they choose to solicit.

The other devs might benefit more from their collaboration than these superdevs.

Anyway, there is a lot of experimentation, too, which sometimes creates lag or goes wrong for a time, but from a broader perspective, things still seem to improve over time.