EasyDoc is open source!

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 origin

Let’s start with a story

From the above story, we can conclude some problems related to documentation during project development:

• The complete business logic is scattered in the prototype diagram, bug system, code notes and brain memory, which is not easy to retrieve and lose.There are significant maintainability costs for continuous iterations of the project
• On projects that are iterative in the long run, only the developers know the details of the business, and newcomers can’t take over. Once the development or product is gone, the business logic is lost, and the transition document doesn’t help much at all.Bring great controllable risk to project research and development
• External operation manual PDF, due to insufficient attention, frequent project iteration, alwaysForgetting to keep up to dateBecome a chicken rib.
• Even with sound documentation, there are many problems encountered during the specific operation of the process.The user experience is poor and requires constant user/operation training and 24-hour problem solving. It would be nice to have a live user guide or instruction manual.

others

• There is only a rough project background, no page or module introduction
• No user guide or inconsistent user guide, weird usage, poor user experience
• Actions are documented, but complex operations with multiple system jumps are not
• No one maintains service documents or the maintenance cost is high

Design solutions to the above problems

• Project documentation:
  • First time: pop-ups to the user when the page is first openedThis section describes the background, objectives, functions, and precautions of the current system
  • Update: re-pop the window in implementing project document updates by controlling the version number
  • Review: Click the EasyDoc button in the upper right corner for further review
• Page document:
  • Open: click the EasyDoc button in the upper right corner to display,The function description of the current page is displayedandPrecautions for UseEtc.
  • Update: Updated by updating the JSON file on the corresponding page
• Page key point document:
  • Open: click the EasyDoc button in the upper right corner to display,Make a note of a key logical point on the pageTo facilitate user or development understanding
  • Update: Updated by updating the JSON file on the corresponding page
• Editable node documents:
  • Open: click the EasyDoc button in the upper right corner to display, which is used to solve: ‘In the architecture mode of the user’s front desk system displaying data, the background system editing the displayed data, to solve the scenario where the operation does not know where to modify the front desk display content’
  • Update: Updated by updating the JSON file on the corresponding page
• The user guide:
  • Open: Call EasyDoc API for operation,Complex processes use user guidance for dumb-ass teachingAnd annotated with key point documents of steps to enhance understanding
  • Update: Front-end development and maintenance
• Operation manual:
  • Open: Click the EasyDoc button in the upper right corner to open,Step annotations for very complex processes with multiple pages or multiple system jumpsTo keep the user on the pageReal time fieldSee the corresponding operation manual, follow the operation manual step by step operation.
  • Update: Updated by updating the project’s action document JSON file

EasyDoc video use demo

EasyDoc Bilibili demo video

EasyDoc technology selection change and iteration

• Version 1 typesciprt + rollup + less + jest

  To package smaller we didn’t use any UI framework and used rollup. Yes, we’re a bunch of young people looking for the best 😎😎, but that led to a lot of trouble at HTML with JS ε=(´ο ‘*)). We decided to use typescript for better maintainability, which really improved the quality of our code and, more importantly, made us realize how important it was. We used the JEST framework to write unit tests, which took some time, but was necessary for an architectural project without dedicated testers. Unit testing has greatly improved the robustness, maintainability, availability and stability of self-research projects.

• Version 2 typescript + rollup + less + + vue2 jest

  Yes, we rewrote the JS DOM code using VUe2, not because vDOM would give us a performance boost, which is not a bottleneck for modern browsers. Mainly because the maintainability of JS dom is too low 😂😂, which also makes us deeply understand the significance of the three frameworks for front-end development.

• Version 3 Vue3 + TS + Element-Plus development visual configuration JSON plug-in

  We found that the interaction form of the json file compiled by the front-end in public was not very friendly to the front-end students, which undoubtedly left the maintenance of business documents to the front-end students. Here’s what we thought at the time: 🤔🤔 :

  For many years, because the front end does not directly contact the business side and the data source, leading to the front end personnel as development resources in the project team, no position, no thinking, no voice, no business growth, no promotion opportunities; We hope that the front end can get close to, master, think and feed the business by assuming EasyDoc to maintain project business documents, improve the position and voice of the front end in the project team, and bring more value to the project from the front end perspective.

  However, when we went to promote, we found that this method had some disadvantages: 1. The product, test and back-end students did not have front-end code permission and could not modify the document. 2. Front-end maintenance of all documentation may be too much. 3. Part of the front end does not want to be close to the business and does not need to be close to the business, and we can not force people. So we developed a plug-in to visually configure JSON files to solve this problem.

• Version 4 lerna

  In order to speed up the first screen rendering, we tried to reduce the size of the main package as much as possible, so we split up some of the side packages, which made our code repository too large. The current development staff is stable so there is no impact, but the hidden danger of warehouse management burden caused by frequent adjustment of developers must be solved in advance 😜😜. So we used Lerna to aggregate all easyDoc-related code together and centrally manage authorization and deployment of NPM.

EasyDoc technology to achieve the scheme thinking process

• Technical requirement: We need to add a text comment to the project, to the page, to a tag
• Technical appeal: We need to establish strong one-to-one correspondence between divs and business document JSON
• Solution 1: Use the Xpath scheme commonly used by blog sites
  • Advantage is no invasion of the page source code; Document and project code are completely decoupled; Anyone can edit and modify it very conveniently
  • The disadvantage is thatIf a page's source code changes and Xpath breaks, it needs to be re-added, and those breaks are not known, maintaining documentation on a project with frequent iterations is a disaster 🤣🤣
• Solution 2: Make a document plug-in using the Vue directive + Element Tooltip
  • The advantage is that DOM borroves Element’s capabilities without additional development, and documents are easily understood and modified by being stored in vue HTML nearby
  • The disadvantage is thatOnly front-end maintenance documents, too dependent on VUE and Element poor universality, too intrusive documents
• Solution 3: Use the tag custom attribute docId to establish a mapping between tags and JSON documents
  • Advantage isThe source code invasion is small, documents and source code decoupling in the project public folder, through the later visual plug-in so that everyone can easily edit and modify 🤞🤞
  • The disadvantage is that documents and projects are not fully decoupled; The need to add docId to the tag is still weakly invasive
• After brainstorming, we decided to implement solution 3

Establish the mapping scheme between HTML tags and JSON documents through docId

EasyDoc code organization diagram

Architecture self-developed project promotion and iteration

• ✨ Pilot operation is very important

  An architecture development project cannot predict user attitudes until it goes live, so pilot projects are necessary and valuable. By observing the stability, ease of use, user posture and user learning cost of the product through pilot projects, a lot of risks and uncertainties can be reduced after formal promotion 😊😊.

• Product launch

  A formal presentation is a great way to promote architecture projects throughout the company, giving you the time to fully talk about your product, and taking advantage of the conferencing screenback feature to continue the promotion. In addition, I can also carry out the collision of thinking with students on the spot and collect students’ ideas and ideas to improve the product. Don’t be afraid of others. It is a very effective way to improve yourself.

• Look for potential customers and sell good products

  Opportunity doesn’t come to you, you have to look for it. We should talk about business documents with the products, front-end, testing and background of other business lines, listen to their ridicule, understand their pain points, empathize with their pain, launch our products and demonstrate, and strike while the iron is hot to win them. If you can’t get it on the same day, record it and return it the next day.

• ✨ Listen to your users, don't contradict them, respond

  Users do not care about the technical implementation details and development problems and difficulties, users only care about their pain points and when they can solve 🤦♂️🤦♂️. Don’t refute the user’s posture or way of thinking. Instead, guide him or accommodate him. You know: a user is a whimpering child who doesn’t know anything, and our mission is to make him comfortable with our product, not whimpering.

  • Story 1: We went to find a product to promote EasyDoc, hoping that she could access it. After listening to the introduction, she felt very good, but the reply business was too busy, so there was no time to write a document to access it. Later, the operation of the product has been ridiculed that the product is difficult to use and will not be used, and the product is badly taught, which reminds us.Since the access to EasyDoc, the product feedback process of teasing and consulting has reduced by more than half 🤦♀️🤦♀️, communication costs have plummeted a lot, and user experience is very good. She’s been a loyal customer ever since.
  • Story 2: The EasyDoc popup window in the upper right corner was originally in hover state, and many application user names click exit login are also in the upper right corner, so it is easy to slip into the EasyDoc panel by mistake. We explain to the user why to make hover popover appear? Is to save the user click this step, this is user experience optimization. butUsers don't care about our optimization points, they only care about the misscribing problem 🤷♀️🤷♀️When we realized that our optimizations were causing side effects to users, we decided to remove the optimizations and switch to click-and-pop.
  • Story 3: EasyDoc was originally fixed on the right after popover, and many background system pages have tables, and the table operation button is also on the right, so our panel blocks the user operation button, requiring the user to switch the EasyDoc panel back and forth. This is not very humane, we are aware of this problem and will optimize it in the next version. But the user asked us several times within 3 days when the change would be finished, and we replied that we would iterate on it with other optimizations in the next version. butIn the eyes of users, we were too slow to fix a small problem and they didn't care about other optimizations 🤷♂️🤷♂️. When we realized this, we took the requirement out and revised it the next night.
  • Story 4: The EasyDoc operation manual was originally separate because each operation manual was a separate module unit. But users think it should be possible to look at one another, or jump to one another, or even link manuals between different systems.We really want to disprove the user that your posture is weird! It's crazy to mess around 🙌🙌. However, we are very qualified. We seriously consider users' demands and redefine the operation mode of the operation manual to meet users' pain points. Users are so cute..

• The user pain point is the goal and value of the iteration

  Software as a service, the user’s pain point is the value point, it is difficult to build a good product behind closed doors.

The architecture manages its own projects upward

• ✨ value and significance (cost reduction, efficiency improvement, business growth)

  Explore, think, summarize and report what the value and significance of the research project is to the company, so that the boss can see the value point and give you more resources input, and your output will be meaningful. At the same time, report the product design of the project, competitive product analysis, feasibility analysis, difficulty solution, but do not make decisions for the boss, leave the final decision to the boss.

  EasyDoc reduces the retrieval cost, communication cost, rework cost and handover cost during development by carrying business documents, and improves the efficiency of getting started, mastering and developing projects. EasyDoc promotes business growth by hosting business documents to reduce understanding time, exploration costs, trial and error costs during user use, improve user experience and retention.

• Align goals (Expectations management)

  We often use the four-quadrant time management method to prioritize the Todo list, but we often ignore the problem that the same self-research project has different priorities for you and the boss 🤣🤣. This is because the criteria we consider are more personal skills and ability growth. The criteria for the boss is “doing things that are more valuable to the company first.” So we need to align the goals of the current quarterly research project with the boss before setting quarterly goals each time. If you don’t align your goals this step is likely to be a waste of human resources 😒😒! .

• Want results, have results, take results (closed-loop thinking)

  We have to have results for the resources committed by our bosses and the resources committed by our dependents; As for the quarterly goals of the self-research project, we must have results. The boss will continue to support you only when you promise to fulfill the commitments. For self-research projects where a lot of human resources are invested, we have to get the expected results, even if you don’t care about individual performance, you have to think about the rest of the team.

Parallel management of self-developed projects

• ✨ Why parallel management?

  Large architecture self-research projects are developed by teamwork, and there may be no relationship between superiors and subordinates, but all equal ranks. It is difficult to reach agreement when opinions clash, and no one can make the final decision. If you go to your boss every time you have a disagreement, it makes her feel incompetent to make a big deal out of it. At this time, parallel management is particularly important. If we can give full play to the parallel management ability and strive for the dotted line to lead the team to promote the project, it will greatly improve our leadership ability and enable the team to achieve good results. Why not?

  • Story 1: When we first got together for a meeting to figure out how to do this, everyone was silent. There was no process, no chair, no decision maker, no minutes, just endless brainstorming and battle. When the meeting was over, I began to reflect:Why is everyone so badass when they get together? 😢 😢In the end I found out it was because there was no role of dashed line leader! So I began to try to push, to undertake, to control each meeting, throughBy deducing the planning before the meeting, controlling the process rhythm during the meeting, and following up the tasks after the meeting, our meetings began to become high-quality and efficient.
  • Story 2: Users will report problems to each developer piecemeal when using our product, and developers will fix them when they have time. However, when the business is busy, it will lead to user feedback being shelved for a long time. We can not blame development students, because others are doing business; But it’s also true that our user feedback is not being addressed. So we started thinkingIt is necessary to establish a process for handling user feedback problems 🤔🤔:
    • 1. Collect and record user feedback and development information through multi-person collaborative documents
    • 2. Identify developers, schedule, progress, and feedback to users
    • 3. Coordinate with other development to follow up in case of personal schedule conflict or blockage
    • 4. Verify the problem and inform the feedback user record modification feedback
    • 5. Review the progress of problems regularly so that no one forgets
    • 6. Periodically review problems and root causes to improve products and R&D processes

• How to manage in parallel?

  ✨ Parallel management is actually the ability of global planning. 1. WBS split architecture targets first, and all member tasks have been reasonably assigned for granularity consideration of the split. Fully consider the ability, willingness, amount of work, and results of the team. 2. Hold meetings to discuss solutions and assign tasks, and put forward reasonable suggestions for problems and give play to the subjective initiative of all; Give suggestions and reasons for delegating tasks in a balanced and prioritized manner. 3. Let all members fill in the development time and completion time of each task, evaluate its rationality and suggest adjustment. 4. Pay attention to the progress of classmates before each time point and deal with it. 5. After the completion of each major stage or encounter major problems, hold a collective review meeting to brainstorm, summarize past failures and make adjustments to future plans.

• Parallel management elements

  Pattern vision, subjective initiative, owner consciousness, planning ability, perspective-taking, moral persuasion…

Development and maintenance personnel

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

Go ahead, don’t look back

Of course, currently open source is only the tip of the iceberg with EasyDoc. The overall picture of our future planning is as follows:

• EasyDoc main package: Load panel and popover,Load other SDK packages dynamically
• EasyDoc Visual configuration package: provides the ability to write JSON business documents visually
• EasyDoc source code and page element mapping package: provides the ability to click on a page div to find the corresponding vUE tag location
• EasyDoc User behavior analysis Feedback Collection package: Provides the ability to collect user behavior and feedback
• EasyDoc Document Management background:Provide the ability to store and modify business documents, realize the complete decoupling of documents and projects, and finally build a collection system of group documents

The road to success is never plain sailing, but the twists and turns are fascinating. On the road of self-development of EasyDoc architecture, we have experienced the passion of working hard, and also experienced the trough of meaningless self-doubt. We have experienced not only the praise from the boss and the user, but also the merciless ridicule from the user that the idea is really hard to use. What we can do is to persevere and become a butterfly 😎😎. When we look back after this journey, we are very grateful for the growth brought to us by this experience. Although our products may not be able to bring much help to the community, we also hope that our experience can give you some inspiration and confidence 💖💖, inspire students to make more priority architecture self-research products, and give students on the road of architecture self-research a little confidence that you will succeed. Go ahead, don’t look back, the road is just spring, the sun is sunny in the sky.

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) ❤ ~