Documentation : New design // Pls. comment

Community Documentation
4

Thanks so much for your initiative here Not_a_countant!

Likely LifeP is referring to how wikis let anyone instantly edit whatever content they find that would benefit from their change, with no need to involve others?

By the same token doc formats, layouts and structure rests with those who feel comfortable and strongly about are maintaining that.

I guess wikipedia achieved their bee-society work culture balance by evolution.

“I am a bit put of by the learning curve.”

Agreed markup is a bit intimidating but not after some short exercise?

5

Thanks!
I am having difficulties in imagining how modules could be structured in wiki. Any good examples? In wiki, an article can have a good structure, but links among article’s are loose. Need ideas :slight_smile:

6

Agree with clarkej
Its easier for all - contributors, developers, users to edit.
It would be particularly helpful to keep up with all the changes and additions, considering the pace with which the feature-set and domains in ERPNext is growing

Secondly,
A wiki also gives scope for making the docs more comprehensive - adding different sections for custom scripts, setup section for developers and an end user section.

7

Would you help make a structure/outline For the wiki? Many thanks for that. Also do you have experience with anything wiki related?

8

Here are some examples of documentation hosted on GitHub Wikis:

1 Like
9

Here are two authorities on what makes wikis tick

http://wiki.c2.com/?WikiPatterns

1 Like
10

Yes surely, No experience with wiki but happy to learn.

1 Like
11

Hi All, thanks for your comments and interests on this topic.

After looking at different tools and examples such as readthedocs, crisp, media wiki, git, python, zerodha, markdowns, intercom, wikihow, google docs and my life time experience in making presentations :

Contribution to perception
80% appearance : of how documentation is perceived is appearance (structure, colors, readability, consistency, spelling, grammar (more forgiving)), lack of segregation of topics
20% content : whether it is outdated, old versions, incomplete, lack of depths.

So if you ask me what is wrong with ERPNext docs is there is

  1. No differentiation of topics (functional, programming, configuration, usage, customization).
  2. Feels like almost everything is thrown is or is widely scattered.
  3. There is no strategy behind it. Basically it has evolved into its own being.

Generally one would feel frustrated with it and hence the constant noise of “documentation is not so good”.
What people are saying is, this could be perhaps better.

Simply put, a level of consolidation & refactoring that should have happened, hasn’t happened.
In other words, too much there is no one with enough energy to carefully curate it.

So here is my proposal and if there is not a violent opposition to it :

I propose to break the entire “documentation” into 4 parts

  1. Beautiful User Documentation (strictly no code) // Zerodha style
  2. Configuration & Settings // Zerodha style
  3. Customization (with code) // GitHub Wiki, Markdowns
  4. DevOps // Wiki, WikiHow

Now each of this needs a OWNER, who will have authority delegated to him/her to make decisions and take it forward.

Anyone opposes this? Any volunteers?

Thanks

2 Likes
12

:+1: :+1: :+1:

BKM

13

:+1::+1:

Wiki is perfectly suitable for the below two.

(3) Customization (with code) // GitHub Wiki, Markdowns
(4) DevOps // Wiki, WikiHow

If no one says anything else, we go with WIKI for these two.
Silence is agreement!

Anyone wanting to take the lead? Write the structure, guidelines, write and curate (3) and (4)

Thanks

14

I agree! this is a great idea to make it like Zerodha style. I wish we at foundation also had the kind of monetary motivation for people to pitch in.

Since documentation revamp is a time-consuming affair, I would suggest asking for volunteers and create a group led by @Not_a_countant. We can have a timeliness and progress tracker like PR’s. I feel that will motivate all of us.

I volunteer to join the group.

1 Like
15

Thanks for your interest. Pls. add your name here. We kick start this in 1 or 2 weeks.
Monetary benefit is just one among many motivators.

16

Consider me in. I’ll also volunteer in creating the documentation.

1 Like
17

Thanks @vijaypatel for your interest. Pls. add your name here. We kick start this in 1 or 2 weeks.

22

Gap finder : Find what is missing in the documentation
Gap filler : Fill that missing gaps
We cant improve what we cant identify is as a short coming.
And I don’t know how else to term this! :slight_smile: Hoep this helps!

23

Here is the beautiful user documentation already worked on by frappe and team! https://erpnext.org/docs/user/manual/en

Since the 2 of the 4 original tasks is pre-emted and done, i will mark it done. Any further improvement should wait for some time for people to look at it and give feedback on what is uptodate and what is not. Most likely 95% there.
So.
Beautiful User Documentation (strictly no code) // Done
Configuration & Settings // Done

For the two below, I look for volunteer to lead the see the gap and fill the gap. We will focus on the two below.
Customization (with code) // Wiki, WikiHow
DevOps // Wiki, WikiHow

Any other thoughts? Welcome!

24

I believe it was already there and no changes done while rewamping the website. I did noticed Screencast of earlier versions being included in their. In some case the references mentioned, might have been moved.

Since, I don’t recall it now, I’ll start going thru them and notify any changes or additions needed in (1).

My question is, how do we keep these documents live with changes in versions of ERPNext from feature point of view and navigation point?

25

This would have been a good point to address with the documentation team as well.
And does it make sense to have a version based documentation approach OR tagging like (feature only v11.2.1) …

The documentation in the way is beautiful, but doesnt meet the pace at which the feature changes unless we say, we only have docs for the latest and greatest and abandon the older version. That might be a strategy. But needs to be agreed.

Good question to follow up.

26

Just courious to know how we preserve the earlier version of core in GitHub. And is it anyway possible to have a backup of earlier docs as a pdf copy or wiki (whatever is best) along with earlier versions.

I read somewhere on GitHub that for book writing project, it’s being used… Maybe we should explore or to fasttrack it, someone good at using GitHub can navigate the documentation team.

With regards to Screencast, I think we should have captions with erpnext version, so that a newbee user doesn’t get lost, if what he/she looking at is outdated - I suffered that pain when I first started :wink:

27

Good points.
These things should go into best practices & writing (screencasting) guidelines.
Keep up the suggestions.