The open source documentation tool I developed has risen to 5300 + star on GitHub, and has been welcomed by some developers. So I want to write an article to share with you the technology and related skills I used in the whole creation process.
Whether it is to do their own planning of product functions, or to do user feedback bugs, ultimately need to refine these points into a single small task, tandem execution (after all, they are a single human). In this regard, I mainly use the team Kanban to achieve my task management. There are a lot of Kanban tools in the team. Just search them. I’m currently using them tower.im
On the Kanban, I create five new lists, which are “doing”, “to do – high priority”, “to do – low priority”, “to be determined” and “remaining problems”. I have the skill to classify them in this way. First of all, it has priorities to ensure that important things are done first. Secondly, it has state management, which is convenient for me to interrupt a task at any time and come back to continue the task after a period of time. At the same time, it can also cope with new tasks – for example, when new requirements come in, I’ll put them in “to be determined” first, and then assign them to other lists when I have time. Finally, it also has a list of “remaining problems”, which allows me to quickly move on to the next task without getting too much time stuck in a certain “complex problem”.
Using Linux or Mac will be very convenient to develop and build test environment, which is undoubtedly convenient for developers. But sometimes the computer needs to play games and install some professional large-scale software. From the perspective of compatibility and universality, I still use Windows system. On win, I use the combination of vagrant + VirtualBox. Vagrant is a set of tools to help you quickly build a virtual machine on the win system by using the VirtualBox, so as to facilitate the use of Linux or Mac (for example, I need MAC virtual machine when Apple App is launched). For this, please refer to a tutorial I wrote a few years ago blog.star7th .com/2015/06/1538.html
I use git as a code version management tool, and I use tortoisegit for visualization.
Tell me how I maintain the online version of showdoc and the open source version of showdoc on the official website. I installed a private version of gogs on my own server as a private git management platform. After the function is developed, I will push it to GitHub. The official website version and the open source version are different branches in the same warehouse at the beginning. The difference between them (especially the difference of back-end code) is growing, so I just divided them into two different warehouses. When doing development, I usually do development and test verification on the official website, and then use the code modification difference comparison function of tortoisegit to migrate the function to the open source version.
Let’s talk about branch management strategy. I set up at least two branches – the main branch and the development branch. The new functions will be implemented in the development branch, and then merged into the main branch after verification. There are also techniques for developing branches. For example, a big function can be done by opening a new branch based on the development branch. For example, if I want to do the a function today, I will operate on the a branch. But the a function has encountered a bottleneck. At the moment, I have no energy to find the bug, so I can start the B branch based on the development branch and continue to do the B function. This is very important, because in the case of limited manpower, I can only do one thing at a time. Such a strategy is conducive to ensure that they interrupt and start tasks at any time, and flexibly arrange different time to deal with easy or difficult problems. This process also needs to be used with the team Kanban mentioned above. Record the progress before interruption, so that you can resume work at any time.
Shell automation script
I wrote three shell automation scripts for showdo. Its functions are to deploy showdoc automatically, generate API documents to showdoc automatically, and generate data dictionary to showdoc automatically. The reason why we choose shell instead of other scripting languages (such as Python) is that shell can basically run on most Linux, and part of it can run on win (installation tools are required), with excellent compatibility and very little dependence. According to the feedback, there are more good reviews than negative ones. Automatic script greatly saves the trouble of user installation environment and reduces the threshold of showdoc. Most of the users of showdoc are not PHP developers, so it’s hard for them to install the PHP environment. With one click scripts, they are easy to use, and I don’t need to spend too much effort on solving novice feedback. This method is universal and language independent (because one click script uses docker to run the service). It can be widely used in open source projects, which is very conducive to the code distribution of open source projects.
By the way, web application developers need to overcome their alienation from shell scripts. When I used to focus on web development, I would subconsciously alienate shell. In Tencent, I consulted my colleagues from another technology stack and found that it was quite simple. Just because of their psychological alienation in the past, I didn’t want to write shell. If you cross this psychological threshold, you will expand your ability boundary. It’s not very different from other languages in writing. It’s just that you need to search and query more grammar.
Back end development
Maybe it’s because showdoc is only a small product, and the background logic involved is not complex, so I don’t spend much time in developing the back end, which is basically crud, adding, deleting, modifying and querying the database. The need for more brain power lies in the team management function, new several data tables, joint implementation of fine authority control.
Showdoc back-end mainly uses domestic framework ThinkPHP. This framework is good and bad. The bad part is that its framework and ecological sharing are relatively general. The good part is that it can quickly roll out a thing, and its compatibility is OK. This is a decision I made when I first developed showdoc four years ago. I didn’t bother to rewrite it with a new framework, so I still use it today. Technology is relatively backward, but also better than good compatibility, can be compatible with the old PHP environment and some old servers. This is still very important, because showdoc is a tool to assist in the development of documents. The better the compatibility, the easier it will be accepted by all kinds of groups. I think this is more practical than using various advanced technologies. Of course, if I’m developing other projects now, I should use laravel or eggjs written by nodejs.
Front end development and UI
I spend a lot more time on front-end development than back-end development. Maybe it’s because it’s an experiential product and we need to do a good job in front-end experience. When starting a front-end page of a product, I suggest that you must choose a UI framework. For example, I choose elementui to do showdoc, while runapi uses Museui (runapi is an online API testing tool used to assist showdoc).
The editor for showdoc is editor.md It’s a product of a few years ago. Although its code organization may be a bit backward, and the original author seems to have a tendency to give up maintenance. But I think it is powerful and concise, so I spent time encapsulating it as a Vue component, and modifying its source code to increase security.
Project drag and page sorting I use the Vue component Vue draggable, but also very easy to use. In the future, there will be drag and drop needs. I guess I’ll still use it.
For icon design, you can use the built-in Font Icon in UI framework, or use Ali mom’s vector icon library. Or use icon for icon design. Here I want to emphasize icon. This tool can easily and quickly use some predetermined patterns and backgrounds to form a quick and usable product icon. The product icon of showdc is made in this way, which can achieve professional effect in a fast and time-saving way. If we make the product bigger in the future, we can consider asking the designer to design it. But in the early stage of the project, icon is enough.
Here I would like to mention the importance of front-end skills. Although the UI framework and corresponding tools can help you save a lot of time. But if you want to make a good product experience, the UI and interaction involved may be beyond the scope of the framework. Therefore, I must learn to use native CSS, interact with JS and encapsulate components. In addition, the front-end skills are also helpful to the app multi terminal development.
App multi terminal development
As for the prototype design of mobile app products, I recommend using “ink knife” to do simple prototype planning. With a visual prototype, you can really save a lot of brain time, so that you can focus on the code in the development phase, without having to write the code, and then go back and think about what functions to do next. Such back and forth switching is quite inefficient.
I use uniapp to develop apps. I use HTML5 and other front-end technologies to encapsulate the code into local apps for mobile phones, including Android apps, apple apps, and even applets. This kind of technology has existed for several years, but its performance has not been good. In 2019, I saw that this area can still develop. So the idea of doing the showdoc app came into being. However, because showdoc focuses on the PC web side, the mobile phone only plays an auxiliary role, so I didn’t do it very carefully. Roughly simplify the web version, reuse some components, rewrite the front end, and then go online. By the way, the app I’ve refined is time tree hole（ blog.star7th . COM / 2019 / 09 / 2380. HTML).
If you want me to evaluate this kind of hybrid app and native app, I will say that native app is definitely the best. Just for the sake of cost and manpower, we can use this H5 technology to deal with some display type products with low requirements for interactive experience. If you are in the verification market stage, you can use similar technology to quickly make a usable product.
In addition, let’s talk about the Apple App. I installed a black apple system on the virtual machine, and then installed the corresponding tools to upload the app to the apple store. About how to open Apple Developer account, how to install Apple system in virtual machine, you can search by yourself.
User feedback and community operation
At first, user feedback consumed me a lot of energy. I’ve become a customer service. Then I started to make some changes, basically getting myself out of the feedback.
First of all, I separated the feedback of the online version and the open source version of the official website. The feedback of the open source version was unified into GitHub (the threshold of using gitbug can filter out some very new novices and avoid novice problems), and the feedback of the online version was sent to the mailbox. If there is a function or bug to change, I’ll put it in the team Kanban first. For some common questions, I’ve sorted out the documents and some fixed reply terms. In addition, I also opened three QQ groups for showdoc users to communicate with themselves. But I want to point out that do not try to answer every question in QQ group, it will drive people crazy. So I changed the group announcement, rewrote the group positioning, and positioned the QQ group as a place for users to communicate on their own. Let enthusiastic users answer the questions that novices encounter when using showdoc. And I just need to look at it very occasionally. Need official support or let users go GitHub or email channel.
However, it is worth mentioning that my operation idea is not suitable for all teams. I have limited manpower and efficiency first, so I filtered a lot of unnecessary feedback. If we have enough manpower, I suggest that we spend more time to help users solve problems, expand the number of users and improve the reputation of products.