I participated in the online chat forum yesterday where the disucssion was about documentation for the Frappe framework, bench and ERP Next. I personally think what is already in place is good and works well for the most part, but I also do think it can be improved.
Right now I see a collection of documentation being available:
ERPNext User Manaul + Videos
Developer Docs
Various blog posts
GitHub Wiki posts
Discussion form posts as a Knowlege Base
What I see is missing is what I could call the administrators guide.
One thing I personally struggle with is the setup and administration of ERPNext. The user manual combines both setup and user instruction. My thinking is to break this into two pieces. The user manual would be reserved for just using the system and incorporated into the new help feature released with v7.1.0. The admin guide is for the admin’s taking care of setup, maintenance, upgrades, customizations, etc. The the developer docs are clearly for the programmers making this awesome platform. Since I am not a developer, I will not speak to the developer guide. I know a number of suggestions were made yesterday in the online chat.
My thinking would be to start another tree in https://github.com/frappe/erpnext/tree/develop/erpnext/docs called “admin” and move some files from the “user/manual” tree over and re-factor the user’s guide to be more procedure based and not technical at all (target audience is the general user). The admin guide would be quite technical in nature as its audience is the technician (and probably developers) taking care of an implementation. This guide would be good for both the self-hosters like me and those who use ERPNext’s hosting services and a lot of the setup and maintenance is the same.
The admin guide would be a place to capture industry best practices for the setup of the various modules and we can use a cook book type format to give tips and tricks as “recipes”. These would come from the community and discussion forum.
Look forward to hearing your thoughts on this.
James
Hello, I couldn’t participate in the online chat but reading this, and as a contribution, I think an admin guide would be great. Also, the developer docs to me seems to be missing a workflow. The stand alone function and docs definitions are very helpful for the amount currently available but it would really help to see the flow of events, triggers and handlers in erpnext.
Thanks Yomi. I read that thread on a mega manual. Those are super hard to maintain and is probably why it died on the vine. I am not a programmer type, so I can’t speak to what is in the dev docs, but it makes sense to have some kind of overview of the platform. Some of that could be in the admin guide and “shared” in the dev docs to reuse the material since it is good for the two audiences.
I am willing to create the branch and start building out the framework, I just don’t want to do the work if too few will find it valuable.
@James_Robertson: system admin guide will be useful indeed. It would be nice to have it started. We will be happy to review and add our tiny bits to that documentation set.
In terms of pulling the right content there, we may want to collect useful pieces already placed in Frappe, ERP Next, and Bench wiki spaces on GitHub, like:
Ok looks like folks are interested in an admin guide. I am very new to github, so I will need to research how to do the work to get started. I assume a good read of the developer docs is in order. Does anyone know of a good resource to develop on windows? I have downloaded github desktop to my workstation and have cloned the repos locally. Is there a way to render the .md files to html on my workstation so I can view what is there before issuing pull request to get my work in the main develop branch?
I assume you are willing to do Frappe-based development related to ERP Next. This is all about cross-platform languages and technology stacks (Python, JavaScript, CSS, HTML5 etc.). Therefore you won’t be developing for Windows platforms specifically. However, you will definitely need some tools to develop on a Windows machine. The main thing is to have a good text editor or IDE tailored for the above-mentioned stack. pyCharm could be a good option for Python development whereas some hardcore developers prefer something like Notepad++ for all languages and tools they ever work with possibly.
As for the markdown-to-html conversion, there are plenty of the options to choose from. One of the well-known applications for that is delivered by http://pandoc.org/ , for instance.
For the most part this is true, however I am not a coder and don’t know Python, JS or JSON. I do however know good 'ol HTML and CSS and was going to contribute to the project via documentation updates. This is why I will “develop on Windows” since I am essentially writing documentation files and not the full software stack. Thanks for the link to the wiki page. I forked erpnext and frappe and have local clones now. I’ll look at pydoc as well.
Could use a bit of help here is possible. @gvyshnya?
I have followed the instructions to fork the projects to my own github repo and have cloned them to my local workstation. I created a branch in erpnext called jwrober_docs that is now synced to my online repo. So all good there. Now I need to figure out the process to render the documentation locally on my computer
and while it is close to what I need (I think), it is mostly about writing docs for an app and then you render with the bench command. Do I need to create a whole 'nother bench for the doc development? e.g. do I have a dev bench that use to clone my forked repo to and then update on my workstation, update on the bench and then gen there?
What is the system that renders the docs in bench?
Ok didn’t do that since I really just want to update the docs on my Windows PC. So with a bit of poking around and a batch script, I figured out how to render most of the docs on my PC using pandoc and a win32 copy of sed. Only thing I haven’t figured out is how {index} tags are pulled into the template from the index.txt files to create the simple table of contents and how {next} tags are translated into navigation.
Before going full bore with the Admin guide, I figured I would start by closing some of the issues labeled for documentation. Did my first pull request.