preface

The open source documentation tool I developed has risen to 5300+ star on Github and is well received by some developers. So I wanted to write an article to share with you the techniques and related skills I used throughout the creation process.

Task management

Whether it is to do the product functions planned by myself or to do the bugs fed back by users, these points need to be refined into individual small tasks and executed in series (after all, I am a single human being). At this point, I mainly use team Kanban for my task management. There are a lot of team kanban tools out there. Just do a search. I personally use Tower.im

On kanban, I created five new lists: “Doing,” “To do – High priority,” “To Do – Low priority,” “To Be Determined,” and “Remaining Issues,” which I skillfully categorized. First of all, it has prioritization, making sure to do what’s important first. Second, it has state management, so THAT I can interrupt a task at any time and come back to it later. At the same time, it can handle new tasks — for example, when a new requirement comes in, I put it on “to do” and assign it to another list when I have time. Finally, it has a “legacy” list that allows me to quickly move on to the next task without spending too much time stuck on a “difficult problem.”

Local development

Using Linux or MAC is very convenient to develop, build test environments, etc., and the convenience for developers is undeniable. But computers sometimes need to play games, need to install some professional large software. For compatibility and universality, I personally use Windows. On Win, I used the combination Vagrant + VirtualBox. Vagrant is a tool that allows you to quickly build virtual machines on Windows using VirtualBox for Linux or MAC(for example, I need a MAC VIRTUAL machine to launch an Apple app). About this, you can refer to a few years ago I wrote a tutorial: blog.star7th.com/2015/06/1538.html

Code management

I use Git as a code version management tool and use Tortoisegit for visualization. Tell me how I maintain showdoc online and open source. I installed a private version of Gogs on my server as my private Git management platform. Once the feature is developed, I will push it to Github. The official and open source versions started out as different branches of the same repository. The differences between them (especially the back-end code) grew so large that I simply split them into two different repositories. When I do development, I usually do development and test verification on the official website, and then use tortoisegit code to modify the difference comparison function and migrate the function to the open source version.

Talk about branch management strategies. I set up at least two branches — the main branch and the development branch. New functionality is done in the development branch, validated and then merged into the main branch. There are also tricks to using development branches. For example, a large function can be done by opening a branch based on the development branch. For example, if I want to do function A today, I’ll do it on branch A. However, function A has encountered A bottleneck, and NOW I have no energy to find bugs, so I can open branch B based on the development branch and continue to do function B. This is important because with limited manpower, I do everything in tandem and can only do one thing at a time. This strategy helps to keep yourself ready to interrupt, ready to jump on tasks, and flexible to schedule different times to tackle easy or difficult problems. This process also needs to be used in conjunction with the team Kanban mentioned above. To record the progress before interruption, convenient to restore their work at any time.

Shell automation script

I wrote three shell automation scripts for Showdo. Showdoc is automatically deployed, API documents are automatically generated to Showdoc, and data dictionaries are automatically generated to Showdoc. The reason for choosing shell over other scripting languages (such as Python) is that shell can run on most Linux and some Windows (installation tools are required), with excellent compatibility and few dependencies. Based on the feedback, there were far more good reviews than negative ones. Automated scripts save users a lot of trouble installing environments and lower the barriers to use showDoc. Most of showdoc’s users are not PHP developers, so it can be tricky for them to install a PHP environment. With the one-click script, it was easy for them to use and I didn’t have to deal with novice feedback as much. This approach is universal and language independent (because one-click scripts run the service using Docker). It can be widely applied to open source projects, which is very conducive to the code distribution of open source projects.

By the way, web application developers, in particular, need to overcome their alienation from shell scripts. When I was a Web developer, I was subconsciously alienated from the shell. When I was in Tencent, I consulted my colleagues in another technology stack and found that it was actually quite simple. Just because I was psychologically distant in the past, I didn’t think about writing shells. When you cross this mental threshold, you will expand your ability to write like any other language, just need to search the syntax.

The backend development

Maybe because ShowDoc is only a small product, and the background logic involved is not complicated, SO I didn’t spend much time developing the back end, which is basically CRUD, adding, deleting, changing and checking the database. The part that needs more brainpower is the team management function, which can create more data tables to realize fine permission control.

Showdoc backend mainly uses the domestic framework thinkPHP. There are pros and cons to this framework. The bad part is that its framework convention, ecological sharing is relatively general, the good part is that it can be quickly out of a thing, and compatibility is ok. This is a decision I made four years ago when I started showDoc, and I didn’t bother to rewrite the framework, so I still use it today. The technology is relatively backward, but it is also better in compatibility, compatible with older PHP environments and some older servers. This is important because ShowDoc is a development aid that assists in writing documents. The more compatible you are, the more likely you are to be accepted by a wide variety of groups. Personally, THIS point is more practical than using all kinds of advanced technology. Of course, if I were developing another project today, I would probably use Laravel, or EggJS written with NodeJS.

Front-end development and UI

I spend a lot more time on front-end development than back-end development. Probably because it’s an experiential product that needs to get the front end right. When starting a product’s front page, I recommend choosing a UI framework. For example, I chose ElementUI as showdoc, while RUNAPI uses museUI (RunAPI is an online API testing tool used to assist ShowDoc).

The editor showdoc uses is editor.md, which is a few years old. Although its code organization may be a bit backward, and the original author seems to have a tendency to abandon maintenance. But I found it powerful and neat, so I took the time to package it as a VUE component and modify its source code to add security.

I use the vUE component VueDraggable for project drag and page sorting, which is pretty easy to use. I’ll probably use it if I need to drag and drop.

Icon design, you can use the UI frame built-in font icon, you can also use Ali mom’s vector icon library. Or use Iconion to design your own ICONS. I want to emphasize the Iconion. This tool makes it very simple and quick to combine a few predetermined patterns and backgrounds into a quick and usable product icon. Showdc product ICONS are made in this way, fast and time-saving to achieve comparable professional results. If you make the product bigger in the future, consider hiring a designer. But at the beginning of the project, Iconion was enough.

The importance of front-end skills is mentioned here. UI frameworks and tools can save you a lot of time. But if you want to do a good job of creating a product experience, the UI and interaction involved may be beyond the scope of the framework itself. So they must learn to use native CSS, JS interaction, will encapsulate components. In addition, front-end skills and multi-side app development as described below also help.

Multi-side app development

For mobile app prototype design, I strongly recommend using “ink knife” to do simple prototype planning. Having a visual prototype really saves a lot of brain time and allows you to focus on the code during development rather than having to write the code and go back and forth to figure out what features to do next, which is quite inefficient.

For APP development, I use UNIApp, and use HTML5 and other front-end technologies to package the code into mobile phone local APPS, including Android APP, Apple App and even small programs. The technology has been around for years, but performance has been tepid. In 2019, I saw that it was still possible. So the idea for the ShowDoc app came up. However, since ShowDoc is mainly on the PC Web, mobile is just a supporting role, so I didn’t do it very carefully. Maybe simplify the Web version, reuse some components, rewrite the front end, and you’re up and running. By the way, I do have to compare the intensification of app is time tree holes (blog.star7th.com/2019/09/2380.html), the app UI will take a little bit of care.

If I had to evaluate this mix of apps versus native apps, I’d say native apps are definitely the best. Just for the consideration of cost and manpower, some display type, interactive experience requirements are not so high products, can use this H5 technology processing. If you are in the validation market stage, you can use similar techniques to quickly make a usable product.

And then there’s the apple app launch issue. I used a virtual machine to install a black Apple system, and then installed the appropriate tools to upload the app to the Apple Store. You can search for information about how to open an Apple developer account and how to install MAC OS on a virtual machine.

User feedback and community operations

At first, user feedback took a lot out of me. Dare to become a customer service. And then I started to make some changes that basically removed myself from that feedback.

First of all, I separated the feedback from the online version of the official website and the open source version. The feedback of the open source version was unified on Github (the threshold of using Gitbug can filter out some very new novices to avoid novice problems), and the feedback of the online version was unified and sent to the mailbox. If there are features or bugs that need to be fixed, I’ll put them in the team kanban. For some common questions, I have organized the documentation and some fixed reply terms. I also opened three QQ groups for showdoc users to communicate with each other. Don’t try to answer every question in your QQ group. It will drive you crazy. Therefore, I changed the group announcement and rewrote the group positioning, positioning the QQ group as a place for users to communicate by themselves. Let dedicated users answer any questions novice users may have while using ShowDoc. I only need to look at it occasionally. Need official support or let the user go to Github or email channel.

However, it is worth mentioning that my approach to business is not suitable for all teams. I have limited manpower and prioritize efficiency, so I filter a lot of unnecessary feedback. If say to have very enough manpower, I pour suggest can spend more time to help user solve a problem, enlarge user quantity already, raise product reputation again.