Looking back on my work experience in recent years, I started with Iceland in the first 17 years within the team, participated in ICE from 1 to 10 in the open source community in 19 years, and founded AppWorks from 0 to 1 in 20 years. He also participated in the early building of the low code engine on the Front end committee of Alibaba. These experiences fall into the category of technology product construction. I’ve seen some interesting ideas and great technical implementations that didn’t succeed in the mundane sense because of the positioning of the product; I have also experienced projects with very systematic planning, but the time window for development was missed due to division of labor and execution problems. It’s hard to serve developers well, they’re extremely picky. It’s not easy to get good engineers to work together. They’re different. I can’t say how many successful experiences I have had in how to serve the developer community and how to manage large collaborative projects, but I have stepped into a lot of holes. When I face the demand for technology productization again, I hope to systematically sort out the construction methods of technical products and summarize my own experience for future use, which may also have some reference value for other students, so I write this article. In this article, I will introduce the “how” methodology, not the “why” motivation. Since the author’s work experience is mainly to build open source technology products, so the article will mainly take “open source technology products” as an example, but I believe these experiences are also applicable to internal technology products. Building a technical product involves designing products, designing architecture, managing projects, writing documents, developing official website, operating products, managing requirements and defects, etc. To do these links well, it is possible to succeed. Technical product projects have different concerns at different stages, such as design in the early stage, operation after release, requirements management and q&A in the stable period, and project management after open source. Following these sections, I will introduce the methodology and tools, and provide some examples.

Design the product

The first step in building a technical product is to define what means to use to solve the problem of the target user, that is, to “do”, which is essentially to complete the design of the user product. At this stage, some input can be made. For example, user research and market research can be used to find out: Which of the user’s concerns are important and urgent? Are there relevant products on the market to solve these problems, and how are they currently solved? From this can be clear, we want to build technology products, positioning is what, what features to provide. In terms of product features, consider: What features do others have that We too have? What features do others have that We can do better? Which features are unique to us? If it is a graphical interface product (such as developer tools), the interactive draft of the product can be produced: what function modules are included, and what is the user’s use process? If it is a code product (such as a framework), the official website interactive draft and document outline can be produced: the process of designing the official website of a product is the process of defining the organizational structure, core capabilities and product values, while the process of writing the document outline is the process of reviewing the user experience of the product from the customer’s perspective. For the base library, you can also start by clarifying the design of the external API: What properties, methods, and events are provided?

To sum up, the main deliverables in product design are:

• Market research report, example: Research Report on Automatic Programming of Artificial Intelligence
• User survey report, example: Research Report on The Current Situation of Front-end Outsourcing of Tao Department Technology Department [Note 3]
• Product interaction draft, example: Iceworks R&D Workbench Product Interaction Draft
• Official website interactive draft, example: ICE official website
• Document outline, example: ICE Tutorial

Design architecture

Product design answers the question of “what to do.” Next comes the question of “how to do.” The essence of product design is to complete the design of software architecture. The importance of software architecture is self-evident. It is the blueprint for system implementation, the basis for communication and collaboration, and determines product quality. There are many mature methodologies on how to design a good architecture and how to describe your architecture design, so I won’t go over them here, but I’m still learning and practicing. In the framework design link one of the author’s ideas is: do competitive product research first, then do the framework drawing.

Do competitive product research, the output is the research report. Through research to understand the architecture pattern of relevant competing products, even the program implementation. There is nothing new under the sun at a time of advanced technical information and active open source communities. What we are about to do has probably been implemented in several versions in several ways. In the limited time, to find the best several implementations in the problem domain for research, standing on the shoulders of giants, twice the result with half the effort. Example: “Ant Could IDE Research Report” [note 4] do architecture drawings and produce architecture diagrams. There are many methods and tools to draw architectures. Most people are most familiar with UML. UML consists of the following two types of diagrams:

• Structural Diagrams: The static structure of the system is emphasized in terms of objects, properties, actions, and relationships. The most common types include the Class Diagram, Component Diagram, and Deployment Diagram.
• Behavioral Diagrams: Emphasizing the dynamic behavior of the system by showing collaboration between objects and state changes within objects, The most common types include the Use Case Diagram, Activity Diagram, Sequence Diagram, and State Machine Diagram.

For example, we can apply these two types of diagrams to our programming:

• Structure diagram: What classes, objects, and functions are included in the program, and how are they related? Class Diagram =>
• Behavior diagram: What is the flow of the program? => Sequence Diagram

Example: VS Code plug-in Time Master programming (source: #PR 620)

Finally, some methodologies and gadgets are recommended for architecture mapping:

1. Methodology: Architecture Mapping: Tools and Methodology by @Chu Heng (Pengqun. Pq) systematically summarizes the methods and tools of architecture mapping, which is worth reading again and again.
2. Finches rich text text drawing function, support PlantUML. PlantUML is a mapping language that allows authors to draw naturally in the same way that a class writes Markdown, allows for multi-person collaboration and version tracking, and is supported by a wide range of knowledge systems:

Manage the project

After the completion of the product and architecture design, the project development began. This session focuses on how to organize development and how to collaborate. The former is common for both individual and team projects, while the latter depends on the size of the project.

Organize project development

Warehouse division

The division of warehouse is the implementation of software architecture design at the level of code organization. It needs foresight to avoid large-scale warehouse migration in the future. There are two kinds of warehouse organization: multi-warehouse and single warehouse. Single warehouse and multiple packages (Monorepo) and single package difference. React, for example, is an organization of multiple warehouses: there’s a main repository, Facebook/React, which is a multi-package repository, and there’s an organization called Reactjs /*, which holds adjacent warehouses. There is no good or bad thing, it depends on the size of the project and the ease of collaboration, or sometimes it’s just a matter of personal preference. For example, some technology products manage their plug-ins, examples, and websites in a separate repository, while others prefer to put them all together. Example: Warehouse partitioning in AppWorks

Branch management

To make the best use of a source code management system like Git to collaborate with multiple people, we need a branch management strategy. The goal of the branch management strategy is to standardize the workflow, allow people to collaborate effectively, and keep the project in order. Branch management policies include the following:

• What are the branching types?
• What is the merge relationship between branch types?
• What is the branching based iteration path?

Common Git workflows include Centralized Workflow, Feature Branch Workflow, Gitflow Workflow, And Forking Workflow. This article, Comparing Workflows by Atlassian, compares these Workflows.

Gitflow Workflow, originally proposed by Vincent Driessen, is widely used in the community:

Git code

The source code of the project is managed based on Git, and it also needs to pay attention to the naming of branches and tags, the format of commit log, and so on. They are standardized so that the project can run smoothly and the project members have a consistent understanding of Git information. There are many Git protocols in the community. There are no good or bad ones. Git commit log format specifications include: log format, word limit, language selection, and so on. The most widely used log formats in the community are:

<type>[optional scope]: <subject>

[optional body]

[optional footer(s)]
Copy the code

Type is used to describe the type of changes submitted this time. Generally, the available values have the following meanings:

• Feat: New function
• Fix: fix the bug
• Docs: Changes related to the document
• Style: Code formatting changes that do not change the code logic (such as indentation, removal and addition of semicolons)
• Test: Adds or modifies test cases
• Refactor: Refactoring code or other optimization
• Chore: Engineering changes to the project without any changes to the code logic
• Revert: Revert a previous commit

For a full version of the Git Commit Message Conventions, see AngularJS Git Commit Message Conventions. Commitlint command line tool (commitlint-config-ali), Git Hooks (commitlint-config-ali), and Git Hooks (Git Hooks) can be used to commit bayonet:

Install the command line tool:

$ npm i --save-dev @iceworks/spec @commitlint/cli husky
Copy the code

Commitlintrc.js: commitlintrc.js: commitlintrc.js: commitlintrc.js: commitlintrc.js: commitlintrc.js

const { getCommitlintConfig } = require('@iceworks/spec'); // getCommitlintConfig(rule: 'common'|'rax'|'react'|'vue', customConfig?) ; module.exports = getCommitlintConfig('react');Copy the code

Add Git Hooks configuration to package.json:

{
  "husky": {
	"hooks": {
	  "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
	}
  }
}
Copy the code

1.@iceworks/spec is a front-end specification package that internally references commitlint-config-ali 2. Husky is a simple Git Hooks configuration tool

Engineering plan

The project engineering plan mainly includes code specification, local engineering and CI&CD content.

Code specifications

Consistency in code style is essential in a multi-person collaborative project. Front field discussion about code specifications and precipitation are more mature, ali front committee standardized groups made [5] the front-end coding statute, including the language (HTML/CSS | Sass | Less/JavaScript) and framework (React/Rax) part. The NPM package @IceWorks/Spec is developed based on this convention. It combines ESLint, StyleLint, Prettier and other command line tools to provide local engineering support. When we do project development, we only need to reference the package and the corresponding command-line tools, and do some simple configuration:

Install the command line tool:

$ npm i --save-dev @iceworks/spec eslint stylelint prettier husky
Copy the code

Configuration package. Json:

{
  "scripts": {
    "lint": "npm run eslint && npm run stylelint",
    "eslint": "eslint --cache --ext .js,.jsx,.ts,.tsx ./",
    "stylelint": "stylelint ./**/*.scss",
    "prettier": "prettier **/* --write"
  },
  "husky": {
    "hooks": {
      "pre-push": "npm run lint"
    }
  }
}
Copy the code

Local engineering

Local development engineering tasks are set to improve development efficiency and implement team specifications into development, usually including the following parts:

• Setup: Initializes the engineering environment
• Dev: Start debugging and preview the sample
• Lint: Performs static code analysis
• Test: Executes unit tests
• Build: Perform the source build
• Publish: Publishes the code

Front-end development has been very mature in local engineering supporting facilities, and there are corresponding engineering solutions for different project types. Examples of common project types and corresponding projects: \

• Front-end application:
• • React application: Use the ICe.js solution
  • Rax applications: Use the RAX-APP solution
• Front-end business components: Use the build-scripts + build-plugin-component solution
• • Rax Business component template
  • React business component template
• Full-stack applications: Use the Midway Hooks scheme
• • Mobile full stack applications
  • Full-stack applications on the PC
• NPM module: use the TSC + Webpack solution
• • Node: github.com/sindresorhu…
  • Browser: github.com/axios/axios

CI&CD

Continuous integration (CI) and continuous deployment (CD) are important components of an automated workflow. On Github, continuous integration is implemented primarily through Actions. Of course there are other options or combinations such as Travis, Appveyor, Circleci, and so on. Github Actions are very powerful and can run under any Github Event. For example, when code is committed to the repository, when a branch is merged, when PR is created, and so on. Tasks based on Github Actions typically include:

• Functional testing and code coverage
• The code to build
• Code checking (syntax checking, security checking)
• Resource deployment (CDN publishing, NPM publishing)

For example, VS Code Suite AppWorks Pack Actions:

• When PR is created: Perform code review and functional test tasks
• When submitting code to beta branch: Perform code build (build plug-in installation package) and resource deployment (upload installation package to CDN) tasks
• When submitting Code to the Main branch: Perform Code build (build the plug-in installation package) and resource deployment (publish the installation package to the VS Code plug-in marketplace) tasks

Within Ali, CI&CD is mainly managed by DEF [note 6] and has a unified automated workflow according to different project types (Assets/WebApp/Serverless).

Establish a cooperative mechanism

Here’s my Activity Overview on Github in 2019, and you can see that a lot of effort was devoted to Issues/PR/CR. For a multi-person collaborative development project, establishing a collaboration mechanism in the early stage is an inevitable requirement to improve the overall efficiency of the team. Once the project is open source, creating a contribution guide allows outside developers to participate in the development of the project. The two are related, and in some open source projects are unified. Some community contribution guide references:

• Contributing Guide for React
• Contributing Guide for VS Code

In the collaboration mechanism, the author thinks that several key contents are: RFC mechanism, PR protocol and CR guidelines.

The RFC mechanism

Some technical products take the form of Request For Comments (RFC) For technical solution design, discussion and iteration of the project, such as React RFCs, Yarn RFCs, Rust RFCs and so on. RFC is a document-first way of working and allows solutions to be fully discussed and demonstrated early in the project.

RFC mechanism mainly includes the following aspects:

1. Categorize: When do I need an RFC

2. Setup process: What are the processes (submission, review, implementation, or delay) and requirements, and what are the responsibilities of each role in each process

3. Provide template: outline of RFC

PR statute

The purpose of PR protocol is to improve the quality of PR and improve the efficiency of CR. Normalized PR can also produce an update log of the product based on the content. PR protocols usually contain the following:

• Protocol for content format: What format should headings and descriptions follow
• Specifications for submitting code, such as test cases for new functionality, package version number for updated code, number of files per PR, and line limit, etc
• The statute of the merger, such as who needs to be approved for the merger

Some open source projects use the PR protocol on the Github App to ensure, for example, that the test code coverage changes. \

CR guide

Highly standardized CR kills productivity, but undemanding CR is often ineffective. The purpose of creating the CR guide is to find a balance between improving the efficiency and effectiveness of CR. A CR guide can contain the following:

1. What are the code review criteria?
2. How are reviewers identified?
3. What should I look for in a code review?
4. What are the methods of file navigation in a code review?
5. How fast should code reviews be responsive?
6. How do I write code review comments?
7. How do I handle receipts during code reviews?

Example: Google’s CR Guide.

The effectiveness of CR can be measured by indicators such as complete reading rate, comment rate, average row review time, etc., so as to establish certain data indicators for the project to restrict CR behavior. \

The efficiency of CR depends on the specific code hosting platform, and you can provide documentation of platform capabilities and tips in the guide. Github, for example, has a well-documented CR feature.

Asynchronous and real time

Most open source projects collaborate in an asynchronous way, rather than working centrally. There are pros and cons, of course, depending on the nature and phase of the project. If asynchronous collaboration is adopted, due to the different personal qualities and work habits of developers, there needs to be a mechanism to ensure the quality and efficiency of the project development. Look at how mature open source projects can operate. For example, VS Code has created annual Roadmap and detailed work plans on a monthly or weekly basis. There is a clear division of labor, whether it is functional modules or process processing (Iusse/PR); There are certain management methods for feedback on requirements and problems. There are also some ways to synchronize the status of the project in real time, such as synchronizing the progress and other information of the project to the online chat room (such as the Nail group) through the robot:

Written document

The most important aspect of a technical product to the user is documentation. The documentation considerations for technical products are: how to provide a good reading experience for users and how to improve the efficiency of writing and reviewing documentation for developers. At present, the mainstream way to read (consume) technical documents in China is: language sparrow, self-built website and Git warehouse; The way to write (produce) is to write on the languge or in the Git repository. The links from production to consumption are: \

1. Write on the finch

• Read on the finch
• Self – built site, request sparrow interface to obtain document content after rendering into a web page

2. Write on the warehouse

• Read in the warehouse
• Build your own site and render Markdown as a web page

The advantages and disadvantages of these links are as follows:

Large projects, or those with open source plans, usually choose the fourth option.

The development of website

Most technology products need an official website to carry product information, or if the fourth option of “writing documents” is selected, you need to consider how to generate a website based on Markdwon for presentation. At present, there are many document website schemes on the community, such as Docusaurus, VuePress, Docsify and so on. The following points can be considered when selecting a model:

• Do you support multiple topics?
• Do you support custom pages?
• Is static site generation supported?
• Is it possible to write documents in multiple languages and versions?
• Is rendering examples in documents supported?
• How about the threshold?
• What is the customization capability and what technology stack is used for customization?
• What is the deployment cost?

Reference: Docusaurus vs. Other Tools

The common choice for open source projects is to deploy to GitHub Pages, where resource hosting and access to domain names are all taken care of. However, domestic access to Github is too slow. One solution is to use the Pages service of a domestic code hosting platform (such as Gitee or Coding) for deployment. Github repository code can be synchronized to these platforms. On the Ali network, the deployment is mainly through DEF. For document sites, there are the following solutions:

For internal technology products, it is not necessary to publish CDN resources to the external network, so it is more appropriate to choose the third scheme under the DEF link.

Operating the product

What kind of mentality should be held

After completing the technical product, we need to take the initiative to operate it. Probably a lot of programmers are not good at this link, feel some claptrap, whore sell melon boast. My point of view is:

1. Technical operation is a kind of technical confidence and responsibility.
2. Wine is also afraid of deep alley, especially in today’s information explosion.

Of course the technology operation should be real and modest:

1. Being authentic means not overstating the features of your product, finding your target audience and solving their problems.
2. Moderation means that the purpose of the operation is to gain exposure and potential users, not to harass others or discredit opponents.

Some questionable actions:

1. Do products with A developer group eight roots are not hit, but get A private chat hair advertising;
2. In the management of the article, I hold the competition against the falling value;
3. To all kinds of competition on the operation of the article crazy paste psoriasis.

What kind of output

In terms of technical operation content, soft articles and dry goods can naturally get more retweets from the technical media. Such articles usually start with the issues and hot technical issues that developers are concerned about and attract readers through the output of solutions. For example, I’ve written “Problems that Affect Coding Flow and what to do about it”, “10 VS Code Tips You may not know about”, “The Material-based Front-end Development Link from Production to Consumption”, and more. Hard wide is also essential, this kind of article mainly tells the function of the product, by telling the truth of the way to express my feelings, such as “Tao department front-end development tools AppWorks official release”, “Iceworks: from GUI development tools to integrated research and development workbench” and so on. There is no doubt that a good title can get more reading for an article. For example, my two articles, The Official release of AppWorks, a developer’s own front-end development tool, were read and interacted more than Iceworks: A Multi-developer Suite. Similarly, an article titled “How to Build a Tech Blockbuster Fast” might be more appealing than “How to Build a Tech Product.” There are even times when I use different titles or content organizations for different outlets: serious state media, mass media and irrigation communities have different sensitivity to titles and preferences for content.

What are the ways

As authors of technical products, they should actively seek more and more suitable channels for technical publicity. Follow from small scope to large scope, gradually spread out the idea of publicity. Teacher Fahai wrote an article “How to Publicize Technical Writing” [note 7], which sorts out publicity channels from the aspects of internal network, public network and private domain. This idea is worth referring to. Finally, the operation of a technology product needs to have both explosive points and continuity. For example, ICE and Rax, which enter the product maturity stage, continuously synchronize the product dynamics through monthly reports and product update logs published by work groups.

Manage requirements and defects

After a technical product is launched, users may submit new requirements or feedback on problems encountered. How to make users get better service experience in a more efficient way is a problem we must face. This aspect author also does not have a good answer, here mainly talk about some practices I see. Open source projects often use issues to gather user needs and questions. Github has the Issue Template feature, which allows developers to use templates to define the content format of different types of issues to guide users to create higher quality issues:

In addition, it is a common management form to categorize issues by means of labels.

The positioning of the Issue is somewhat similar to the “work order model” for commercial products. Maintainers of open source projects have no way to respond to all users’ needs and problems. They expect the community to help each other solve problems, so they create online communication channels for users to communicate with each other. For example, foreign open source projects often use Stack Overflow or Github Discussions to create online discussion boards, and Discord to create real-time online chat rooms. The “mutual aid mode” of domestic community is mainly to use various office communication software (such as Nail) to create user groups. A common practice for Alibaba’s in-house technology products is to use Aone to track requirements and defects, and access RESEARCH and development honey to provide q&A services. Thanks to these tools, the demand and defect management of technology products can be online in Ali. In the future, the input and output of the technical team can be evaluated digitally. For example, the middle Taiwan team can include the q&A resolution rate, Aone demand/defect processing rate and other indicators in the performance assessment. In-house technology products should be held to the same standards as commercial products.

Write in the last

The picture is the wood products made by the author when participating in a manual activity. I remember clearly how easy it was to shape the car in just a few steps using a large cutting tool. But to really make it a craft, it takes patience and a lot of time to smooth out its water chestnut. I think the same is true of technology products. The rules in the text are just a general outline of a technology product, and it takes a lot of fine-tuning, iterative work to make it truly usable and enjoyable for developers.

annotation

1. Note 1: Iceland is the internal interface design platform of Tao
2. Note 2: Ali low code Engine is an SDK for low code areas
3. Note 3: The Research report on the Current situation of front-end Outsourcing of Tao Department technology Department is an internal document, which reports the research and development status of Tao Department outsourcing
4. Note 4: “Ant Could IDE Research Report” is an internal document. Could IDE is a code-centered, professional and efficient cloud RESEARCH and development platform of Ant
5. Note 5: Front-end Coding Protocol is an internal document, which is part of ali front-end standardization document
6. Note 6: DEF is ali’s internal front-end engineering r&d platform
7. Note 7: “How to promote technical Writing” is an internal article that describes how to use Alibaba’s internal media channels to promote technical writing
8. Note 8: Aone is a one-stop r&d collaboration platform within Alibaba
9. Note 9: RDA Is a SaaS solution platform for internal service and support scenarios in Alibaba

— — — — — — — — — — — — — — — — — — — — — —

The author | the cream

Edit | orange

New retail product | alibaba tao technology