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

npm i we-easydoc --save

Initialization

// 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"
})

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

// 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'
  }
})

Project Documentation

Define project docs in public/easy-doc/Projects.json with fields name, description, and auth. Multiple entries are allowed.

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

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.

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

Node Documentation

Define node docs with docId, description, auth, optional direction, and zIndex. Attach docId to DOM elements.

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

Editable Node Documentation

Link editable nodes to backend edit pages via editUrl.

{
  "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"}
  ]
}

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.

[
  {
    "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"}]}
    ]
  }
]

User Guides

Initialize and start guides with EasyDoc.initGuide and EasyDoc.startGuide. Guides consist of steps that point to specific docId nodes.

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

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!