How EasyDoc Simplifies Project Documentation and User Guides

What is EasyDoc

EasyDoc is an easy‑to‑configure, cost‑effective project documentation system designed to lower the learning curve of complex projects, reduce information gaps among team members, and move documentation from developers to dedicated tools.

Key Benefits

Reduce onboarding difficulty

上手难度

and improve user experience.

Bridge information gaps

信息差

between new and existing team members.

Shift documentation responsibility from

开发者

to

文档工具

.

How It Works

Documentation is delivered through user guides, operation manuals, page explanations, node annotations, and editable node docs, all defined in JSON files and linked to DOM elements via

docId

attributes.

Installation

<code>npm i we-easydoc --save</code>

Initialization

<code>// Use default parameters
import EasyDoc from 'easy-doc'
EasyDoc.init()

// Custom parameters
EasyDoc.init({
  urlPrefix: "/easy-doc",
  easyDocPath: "/public/easy-doc/EasyDoc.json",
  easyManualsPath: "/public/easy-doc/Manuals.json",
  easyProjectsPath: "/public/easy-doc/Projects.json"
})</code>

Configuration Parameters

Parameter

Type

Required

Default

Description

easyDocPath

string

No

/easy-doc/EasyDoc.json

easyManualsPath

string

No

/easy-doc/Manuals.json

easyProjectsPath

string

No

/easy-doc/Projects.json

minHeight

number

No

100

Minimum height of the documentation popup.

minWidth

number

No

200

Minimum width of the documentation popup.

maxWidth

number

No

450

Maximum width of the documentation popup.

editHeight

number

No

Fixed height for editable node popups.

editWidth

number

No

Fixed width for editable node popups.

urlPrefix

string

No

Prefix added to all EasyDoc requests.

env

string|function

No

DEVELOPMENT

Visibility scope: DEVELOPMENT > TEST > PRODUCTION.

showGuideMask

boolean

No

false

Show translucent mask under nodes.

mountPanel

boolean

No

true

Mount the top‑right control panel.

ignorePaths

string[]

No

[]

Page paths where EasyDoc is disabled.

hasEasyDocJSON

boolean

No

true

Whether to request EasyDoc.json.

hasManualsJSON

boolean

No

true

Whether to request Manuals.json.

hasProjectsJSON

boolean

No

true

Whether to request Projects.json.

Environment Configuration

<code>// Set environment directly
EasyDoc.init({ env: 'pro' })

// Compute environment dynamically
EasyDoc.init({
  env: () => {
    switch (process.env.NODE_ENV) {
      case 'production': return 'pro'
      case 'test': return 'test'
      case 'development': return 'dev'
      default: return 'pro'
    }
  }
})

// Determine environment by URL
EasyDoc.init({
  env: () => {
    if (window.location.href.includes('.guahao.cn')) return 'pro'
    if (window.location.href.includes('.guahao-test.com')) return 'test'
    return 'dev'
  }
})
</code>

Project Documentation

Define project docs in

public/easy-doc/Projects.json

with fields

name

,

description

, and

auth

. Multiple entries are allowed.

<code>[
  {"name":"Diting最佳实践","description":"...","auth":"pro"},
  {"name":"Gtrace-最佳实践","description":"...","auth":"pro"}
]
</code>

Page Documentation

Map routes to JSON files in

public/easy-doc/Easydoc.json

using

match

(regex) and

jsonFile

. Each page JSON contains

name

,

description

, and

auth

.

<code>[
  {"match":"/user/list","jsonFile":"/public/easy-doc/user3.json"},
  {"match":"/dept/list/[0-9]+","jsonFile":"/public/easy-doc/dept.json"}
]
</code>

Node Documentation

Define node docs with

docId

,

description

,

auth

, optional

direction

, and

zIndex

. Attach

docId

to DOM elements.

<code>{
  "docs": [
    {"docId":"dept-list","description":"当切换为运行状态时...","auth":"pro","direction":"LT","zIndex":100},
    {"docId":"dept-btn","description":"方方速递...","auth":"dev","direction":"BR"}
  ]
}
</code>

Editable Node Documentation

Link editable nodes to backend edit pages via

editUrl

.

<code>{
  "edits": [
    {"docId":"dept-list","editUrl":"https://example.com/edit","auth":"dev","direction":"TL","zIndex":200},
    {"docId":"dept-btn","editUrl":"https://example.com/edit","auth":"test","direction":"LB"}
  ]
}
</code>

Operation Manuals

Define interactive manuals in

public/easy-doc/Manuals.json

. Each manual has

name

,

description

,

initUrl

, and a series of

steps

with linked nodes.

<code>[
  {
    "name":"操作手册A",
    "description":"...<a href='http://example.com'>去WCP</a>",
    "initUrl":"/dept/list",
    "steps":[
      {"url":"/dept/list","description":"第一步有两个按钮高亮","nodes":[{"docId":"dept-open-btn1","description":"节点1","auth":"pro"},{"docId":"dept-open-btn2","description":"节点2","auth":"pro"}]}
    ]
  }
]
</code>

User Guides

Initialize and start guides with

EasyDoc.initGuide

and

EasyDoc.startGuide

. Guides consist of steps that point to specific

docId

nodes.

<code>EasyDoc.initGuide({
  name: '用户引导A',
  steps: [
    {url: '/dept/list', node: {docId: 'guide1', description: '用户引导A第一步节点1', auth: 'pro'}},
    // ...more steps
  ]
})
EasyDoc.startGuide()
</code>

Advanced Usage

Multiple

docId

syntaxes (doc-id, data-docId, etc.) are supported.

Direction codes (TL, TR, TC, RT, RB, RC, BL, BR, BC, LT, LB, LC) control popup placement.

Use

urlPrefix

to handle environments with custom URL bases.

Disable JSON requests with

hasEasyDocJSON

,

hasManualsJSON

,

hasProjectsJSON

to avoid 404 noise.

GitHub Repository

https://github.com/wefront/we-easydoc

Give us a star if you like the project!