What is EasyDoc

  • WHAT: EasyDoc is aEasy to configure cost reduction and efficiency of the project documentation system
  • According to:
    • Reduce complex projectsTo fit the difficultyTo improve user experience
    • Smooth out the new and old members of the project teamInformation gap
    • Carrier the business details of the project fromdevelopersChanged to:Documentation tool
  • HOW: Go through the processThe user guide, processes,Operation manual, pagedocumentation,Project descriptionThe document,Key notesDocuments and other ways to achieve
  • Status: EasyDoc has been incubated in Wedoctor Group for more than a year, has been connected to more than a dozen online applications, and is being comprehensively promoted within the group. And open source to the community,Hoping to bring a little new blood into the community, we look forward to your use and access. If you have any questions, please leave a comment or give us your opinion on Github.
  • Typical scenario: Management background, complex forms, complex processes, and complex interactions 😉😉
  • Unsuitable scenarios: large-screen projects and game projects 🤣🤣

EasyDoc video use demo

EasyDoc Bilibili demo video

EasyDoc Tutorial

1. Install dependencies

npm i we-easydoc --save
Copy the code

2. Initialize parameters

// Use the default parameters
import EasyDoc from 'easy-doc'
EasyDoc.init()

// Customize parameters
EasyDoc.init({
  urlPrefix: "/easy-doc".easyDocPath: "/public/easy-doc/EasyDoc.json".easyManualsPath: "/public/easy-doc/Manuals.json".easyProjectsPath: "/public/easy-doc/Projects.json"});Copy the code
  • Easydoc.init function parameter description
parameter type mandatory The default value instructions
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 document node popup
minWidth number no 200 Minimum document node popover width
maxWidth number no 450 Maximum document node popover width
editHeight number no Fixed height of editable node pop-ups
editWidth number no Fixed width of editable node popovers
urlPrefix string no The static resource path prefix is automatically added to all EasyDoc requests
env (() => AuthEnum) | string no ‘DEVELOPMENT’ ‘DEVELOPMENT’> ‘TEST’ >’PRODUCTION’
showGuideMask boolean no false Whether a translucent layer is displayed below the node when it is displayed
mountPanel boolean no true Whether to mount the upper-right corner panel
ignorePaths string[] no [] Do not enable the easyDoc page path array
hasEasyDocJSON boolean no true Whether to request easydoc. json file
hasManualsJSON boolean no true Ask for the Manuals. Json file
hasProjectsJSON boolean no true Whether to request a projects. json file
  • Env parameter extension description
    • ‘dev’ or ‘DEVELOPMENT’ indicates production environment, test environment, DEVELOPMENT environment all documents visible
    • ‘test’ or ‘test’ indicates that production and test environments can see all documents
    • ‘Pro’ or ‘PRODUCTION’ indicates that the PRODUCTION environment sees all documents
Dev > test > pro
EasyDoc.init({
  env: 'pro'.// dev | test | pro
})
// You can pass in the function to evaluate
EasyDoc.init({
  env: () = > {
    switch (process.env.NODE_ENV) {
      case 'production':
        return 'pro'
      case 'test':
        return 'test'
      case 'development':
        return 'dev'
      default:
        return 'pro'}}})// Can be determined by domain name suffix
EasyDoc.init({
  env: () = > {
    if (window.location.href.indexOf('.guahao.cn') > -1) {
      return 'pro'
    }
    if (window.location.href.indexOf('.guahao-test.com') > -1) {
      return 'test'
    }
    return 'dev'}})Copy the code

3. Write project documentation

The project document is an introduction to the whole project, notes for attention, etc. It will automatically pop up when the project is opened for the first time and will not automatically pop up after that to clear the browser cache failure. It can also be viewed by clicking on the project document in the upper right corner.

  • Public /easy-doc/ projects. json (static folder may also be static instead of public)
  • Name: project document name
  • Description: Project document content
  • Write plain text or insert HTML, especially jump a links
  • Auth: Project document visibility
  • Multiple project documents can be written. If there are no project documents, skip this step
[{"name": "Diting Best Practices"."description": "Detailed introduction to Diting best practices detailed introduction to Diting best practices."auth": "pro"
  },
  {
    "name": "Gtrace- Best Practices"."description": "Gtrace- Details of Best Practices Gtrace- Details of Best Practices."auth": "pro"
  },
  {
    "name": "Kano Best Practices"."description": "A detailed introduction to Kano best practices a detailed introduction to Kano best practices a detailed introduction to Kano best practices"."auth": "pro"
  },
  {
    "name": "MQ Best Practices"."description": "Detailed introduction to MQ best Practices Detailed introduction to MQ best practices detailed introduction to MQ best practices."auth": "pro"
  },
  {
    "name": "Configuration Center GConfig Best Practices"."description": "Detailed description of gConfig best practices in the Configuration center Detailed description of gconfig best practices in the configuration center detailed description of GConfig best practices in the configuration center."auth": "pro"}]Copy the code

4. Document the page

A page document is an introduction and notes to a page. Using easydoc. json to specify the mapping between the page and JSON file, and then write in json file.

  • public/easy-doc/Easydoc.json
  • Match: indicates the regular expression for matching routes
  • JsonFile: indicates the path of the CORRESPONDING JSON file
[{"match": "/user/list"."jsonFile": "/public/easy-doc/user3.json"
  },
  {
    "match": "/dept/list/[0-9]+"."jsonFile": "/public/easy-doc/dept.json"
  },
  {
    "match": "/handle-doc.html"."jsonFile": "/public/easy-doc/handle-doc.json"},]Copy the code
  • public/easy-doc/user3.json
  • Name: indicates the page description name
  • Description: Indicates the page description
  • Auth: Page description visibility range
{
  "pages": [{"name": "Introduction to the first User page"."description": "This is a piece of content."."auth": "dev"
    },
    {
      "name": "Introduction to the first User page"."description": "Here's another one."."auth": "test"}}],Copy the code

5. Write page node documents

A page node document describes a node on a page and notes precautions. Easydoc.json is used to specify the mapping relationship between the page and THE JSON file, and then the document is written in the JSON file, and docId is added on the DOM node of the page to realize the mapping.

  • public/easy-doc/Easydoc.json
  • Match: indicates the regular expression for matching routes
  • JsonFile: indicates the path of the CORRESPONDING JSON file
[{"match": "/user/list"."jsonFile": "/public/easy-doc/user3.json"
  },
  {
    "match": "/dept/list/[0-9]+"."jsonFile": "/public/easy-doc/dept.json"
  },
  {
    "match": "/handle-doc.html"."jsonFile": "/public/easy-doc/handle-doc.json"},]Copy the code
  • public/easy-doc/user3.json
  • Name: indicates the page description name
  • Description: Indicates the page description
  • Auth: Page description visibility range
  • Direction: specifies the direction of the node pop-up. This parameter is optional
  • ZIndex: Specifies zIndex to prevent occlusion. This parameter is optional
{
  "docs": [{"docId": "dept-list"."description": "When switched to the running state when switched to the running state when switched to the running state"."auth": "pro"."direction": "LT"."zIndex": 100
    },
    {
      "docId": "dept-btn"."description": "Square express express express express, one push button express, one push button express,"."auth": "dev"."direction": "BR"}}],Copy the code
  • /user/list Corresponding vue file
<div>
  <div docId='dept-list'>User list page HTML<div>
    <el-button docId='dept-btn'>BTN of the user List page<div>
</div>
Copy the code

6. Write editable node documents

Editable node documents are used for the foreground system display, and the latter system edits the scene of the foreground display content. In this scenario, connect a piece of content in the foreground with the editing page of the content in the background, and click to directly jump to the past for configuration, which is convenient for product operation. Easydoc.json is used to specify the mapping relationship between the page and THE JSON file, and then the document is written in the JSON file, and docId is added on the DOM node of the page to realize the mapping.

  • public/easy-doc/Easydoc.json
  • Match: indicates the regular expression for matching routes
  • JsonFile: indicates the path of the CORRESPONDING JSON file
[{"match": "/user/list"."jsonFile": "/public/easy-doc/user3.json"
  },
  {
    "match": "/dept/list/[0-9]+"."jsonFile": "/public/easy-doc/dept.json"
  },
  {
    "match": "/handle-doc.html"."jsonFile": "/public/easy-doc/handle-doc.json"},]Copy the code
  • public/easy-doc/user3.json
  • Name: indicates the page description name
  • Description: Indicates the page description
  • Auth: Page description visibility range
  • Direction: specifies the direction of the node pop-up. This parameter is optional
  • ZIndex: Specifies zIndex to prevent occlusion. This parameter is optional
{
  "edits": [{"docId": "dept-list"."editUrl": "https://fanyi.baidu.com/translate?aldtype=16047&keyfrom=baidu&smartresult=dict&lang=auto2zh#ru/zh/EasyDoc"."auth": "dev"."direction": "TL"."zIndex": 200
    },
    {
      "docId": "dept-btn"."editUrl": "https://fanyi.baidu.com/translate?aldtype=16047&keyfrom=baidu&smartresult=dict&lang=auto2zh#ru/zh/EasyDoc"."auth": "test"."direction": "LB"}}],Copy the code
  • /user/list Corresponding vue file
<div>
  <div docId='dept-list'>User list page HTML<div>
    <el-button docId='dept-btn'>BTN of the user List page<div>
</div>
Copy the code

7. Write operation manual

The operation manual is a dynamic real-time operational instruction manual. Click it to automatically jump to the first page corresponding to the operation manual, and follow the step-by-step practice, which is convenient for novices to better learn the use of the system and understand the business information hidden behind the functions.

  • public/easy-doc/Manuals.json
  • Note: You can jump from one manual to another by specifying type=link, linkManualName= manual name
  • You can add a link in the description of the step to realize the external chain jump
  • Be sure to add the step docId to the DOM of the corresponding page
[{"name": "Operation Manual A"."description": "This is about the operating manual is A description of the < A href =" http://wcp.gops.guahao.cn/frontend-refactor/home/page "> to WCP < / A >"."initUrl": "/dept/list".// The initial URL will be jumped to when the manual is opened
    "steps": [{"url": "/dept/list"."description": "Operation Manual A has two buttons highlighted in the first step."."nodes": [{"docId": "dept-open-btn1"."description": "Operation Manual A step 1 node 1"."auth": "pro"."zIndex": 1000 // Specify zIndex to prevent occlusion, optional
          },
          {
            "docId": "dept-open-btn2"."description": "Operation Manual A step 1 node 2"."auth": "pro"}}],.. steps// Multiple steps are omitted here
      
  {
    "name": "Operation Manual B"."description": "This is the description of operation manual B."."initUrl": "/user/list".// The initial URL will be jumped to when the manual is opened
    "steps": [{"url": "/user/list"."description": "Operation Manual B has two buttons highlighted in step one."."nodes": [{"docId": "dept-open-btn2"."description": "Operation Manual A step 1 node 2"."auth": "pro"}]}, {"description": "Click from Operation manual B to operation manual A."."type": "link"."linkManualName": "Operation Manual A"}]]Copy the code

8. Write a user boot

User bootstraps are fixed step bootstraps that show how to use a new feature for the first time.

  • Easydoc. initGuide(Guide: GuideNode) initializes user boot data
  • Easydoc.startguide () starts the current user boot
  • EasyDoc.jumpGuideStep(stepIdx: number, guideStep? : GuideStep) jumps to the current user-guided step, counting from 0; The second argument is passed in to replace the current step
  • Easydoc. closeGuide() actively closes the current operating manual
  // Initialize the user boot data
  EasyDoc.initGuide({
    'name': 'User boot A'.'steps': [{'url': '/dept/list'.'node': {
          'docId': 'guide1'.'description': 'User boot 

A step 1 node 1'.'auth': 'pro'}}, {'url': '/dept/list'.'node': {
          'docId': 'guide2'.'description': 'User boot A step 1 node 2'.'auth': 'pro'}}, {'url': '/dept/list'.'node': {
          'docId': 'guide3'.'description': 'User boot A step 1 node 3'.'auth': 'pro'}}, {'url': '/dept/list'.'node': {
          'docId': 'guide4'.'description': 'User boot A step 1 node 4'.'auth': 'pro'}}, {'url': '/dept/list'.'node': {
          'docId': 'guide5'.'description': 'User boot A step 1 node 5'.'auth': 'pro'}}, {'url': '/dept/list'.'node': {
          'docId': 'guide6'.'description': 'User boot A Step 1 node 6'.'auth': 'pro'}}},])// Start the current user boot
  EasyDoc.startGuide()
  // Skip to step 4 after 4 seconds and modify step 4 without displaying the next button
  setTimeout(() = > {
    EasyDoc.jumpGuideStep(3, {
      'url': '/dept/list'.'node': {
        'docId': 'guide4'.'description': 'Manually modify content'.'auth': 'pro'
      },
      next: false.// Whether to display the next button})},4000)
  // Close the current user boot after another 3 seconds
  setTimeout(() = > {
    EasyDoc.closeGuide()
  }, 7000)
Copy the code

EasyDoc extension usage

1. Multiple compatible writing methods of docId

  • DocId, doc-id, docId, data-docid, data-doc-id, and data-docid can all be matched
  • DocId cannot start with a number
  • Multiple docId can be written to a DOM node, separated by Spaces
  • A single docId can also match multiple DOM nodes on the current page. Setting noUnique=true is optional. By default, one page can match only one DOM node
<div docId="user-list-query user-list-search"></div>
<div docId="user-btn user-list-query"></div>{" docs ": [{" docId" : "user - BTN - query", "description" : "click query user list", "auth" : "dev" and "direction" : "BL", "noUnique" : True // Single docId can also match multiple DOM nodes on the current page}]}Copy the code

2. Direction Indicates the orientation of the popover

  • Direction is an optional property that defaults to an adaptive position and allows the user to specify the orientation to adjust the display
  • TL on the left
  • Right on the TR
  • TC high
  • RT upper right
  • RB right
  • In the RC right
  • Key levels BL
  • BR right
  • In the BC under
  • LT upper left
  • LB lower left
  • LC in the left

3. Path prefix

  • Some systems configure url prefixes. For example, the URL prefix of the JSON file corresponding to www.baidu.com is www.baidu.com/easy-doc/Ea… When the prefix frontend-refactor is configured, the access path becomes www.baidu.com/frontend-re… The JSON file cannot be found. We just need to add the urlPrefix parameter during initialization.
  EasyDoc.init({
    urlPrefix: "/frontend-refactor".easyDocPath: "/public/easy-doc/EasyDoc.json".easyManualsPath: "/public/easy-doc/Manuals.json".easyProjectsPath: "/public/easy-doc/Projects.json"});Copy the code
  • What if the online address of a website does not match the test address? The scheme is as follows:
let urlPrefix = ` `
let easyDocPath = `/public/easy-doc/EasyDoc.json`
let easyManualsPath = `/public/easy-doc/Manuals.json`
let easyProjectsPath = `/public/easy-doc/Projects.json`
/ / online
if (location.origin === 'http://xxxxx') {
  urlPrefix = `/frontend-refactor`
  easyDocPath = `http://xxxxx/frontend-refactor/public/easy-doc/EasyDoc.json`
  easyManualsPath = `http://xxxxx/frontend-refactor/public/easy-doc/Manuals.json`
  easyProjectsPath = `http://xxxxx/frontend-refactor/public/easy-doc/Projects.json`
}
EasyDoc.init({
  urlPrefix,
  easyDocPath,
  easyManualsPath,
  easyProjectsPath
})
Copy the code

4. Error 404 is reported when the F12 network cannot find the JSON file

  • Json, Manuals. Json, Projects. Json files may not have been configured for the project at the time, so the network will report 404 that the file cannot be found.
  • This problem does not affect business, but the business side always suspects that there is something wrong with Easydoc when they see the 404 error of Easydoc when looking for business bug, so we will optimize and deal with it.
EasyDoc.init({
  hasEasyDocJSON: false.// The default value is true. If it is false, json will not be requested
  hasManualsJSON: false.// The default value is true. If it is false, json will not be requested
  hasProjectsJSON: false.// The default value is true. If it is false, json will not be requested
});
Copy the code

5. CHANGLOG.md

Through this file, you can see the content introduction and corresponding version of each update, and understand the historical development of EasyDoc

Other: Other questions

For other questions, please contact the developer online.

  • Li Yuntong 😜 😜
  • Yang Yizhen 😎 😎
  • Junin ✌ ✌
  • JiaoChuan wenkai 😉 😉
  • QuanMing Yang 😘 😘
  • Dan-dan huang 🤞 🤞

read

  • You have to know the design pattern TS edition
  • You have to know the methodology of the problem of the factory
  • Do you really know how to refactor code
  • Is it necessary to master the minutiae of framework source code?
  • Vue3 source analysis: explain the beginning of the source code

EasyDoc gitbub address

Github.com/wefront/we-… Remember to give us a thumbs up ✨✨ and the star we understand you guys 🤞🤞 (our guys understand you guys) ❤ ~