今日推薦開源項目：《前人的經驗 flutter-go》
今日推薦英文原文：《Learning, Coding, & Freelancing as a Dad》
今日推薦開源項目：《前人的經驗 flutter-go》傳送門：GitHub鏈接
推薦理由：為使用 Flutter 的大家提供的助手。這個 app 可以作為使用 Flutter 的示例，包含常用組件的中文文檔和演示。Flutter 是一個移動開發框架，想要詳細了解的話可以看看這裡（GitHub鏈接），它的 star 數已經證明了它是一個相當不錯的框架了。當然了，雖然配合上中文文檔食用更佳，不過還是鼓勵大家提高自己的英語水平，畢竟直接看英文文檔才是最快了解新技術的辦法。
今日推薦英文原文：《Defeating the Scary Documentation Monster》作者：Kristiina Ritso
原文鏈接：https://medium.com/mobi-lab/defeating-the-scary-documentation-monster-5265596b4b92
推薦理由：寫文檔實際上並不是完全沒用的事情，你永遠不會知道你什麼時候需要回來看看它的
Defeating the Scary Documentation Monster
「Hey! Can you write that end-user documentation about the app we』re developing?」 — 「 I』ll get to that when I have time.」
Ever had that kind of conversation and never actually ended up writing the damn thing because some other, higher priority task came along? Everything』s agile, moving fast and features get the focus. How can documentation bring value when it』s quite often considered waste?
In our lives we have all come to contact with some form of documentation, let it be technical requirements, API specifications, recipes, board game or furniture assembly manuals. We find them useful and reassuring, even if we will never read them more than once. One of the main points in agile software development is to produce software, not documentation. What happens when things go too extreme, and you end up in a situation where there』s no documentation at all or very little of it? Well, we were there.
Documentation can play a huge role. It can affect the developers when they need to return to a project that has been sitting on a shelf for years or onboard a new team member. It can be a significant risk for the client when the product has to be handed over, and they start maintaining it themselves. Without a proper set of minimum viable documentation, it can become more expensive than writing it in the first place. Sadly, when it was the right time to start, priorities laid on different aspects of the development process. Quite often it is the budget that sets the boundaries because the value is not always visible or arrives too late. So how can we make it valuable for everybody without putting a big hole in our budget?
Starting Steps: onboarding a team member
There are many projects in our development vault. Some of them well documented, some have a line or two written down in the README file, and some have information laying around in all sorts of communication channels. Writing documentation seemed to be like fighting a monster. Some took up the challenge only to find that it was not that scary. Others decided to let somebody else deal with it. We wanted to make it less intimidating and turn it into a natural part of the process. For that, we had to start from the beginning.
We first saw places for improvements when we had to onboard a new developer to the team. Our challenge was to find a way to communicate the development process as efficiently as possible and provide a source for the new person to come back to. We created a template for the team members to fill which listed all development related information and workflow of the team. This template helped the initial developers not to miss any vital information and gave the new team member a place to come back to when they needed it. Fortunately, a perfect situation occurred. Two projects exchanged developers. This gave us an excellent testing field for the template to validate the solution. The developers filled the document and carried out the onboarding process for each other. Instantly we could get feedback and revise the template. With a little effort and luck on our side, we already had a solid starting ground.
Okay, but this only solves one problem — having documentation for onboarding. We were still lacking documentation for smaller scale projects and a habit of creating it.
Moving forward
We had done our fair share of only-ifs and what-if』s, got burned from past mistakes and licked our wounds. Now it was time to take action so we could improve.For larger systems and projects we have enough documentation. This is part of our process that starts with drafting architecture and analyzing requirements. For smaller scale projects, these phases are shorter and therefore do not always produce enough documentation.
From the onboarding template, we found a way to generate a starting point for the project』s ReadMe. There are many examples of ReadMe-s available, but we needed something that was custom made for our company』s processes. We started with defining the roles in the development phases. Mapping down all the parties helps to identify common information needed. Once we had them mapped, we also took a more in-depth look into what those parties are interested in. For example, there is no need for the designer to know all the technical constraints, but they are interested in where to find the application and whom to contact when they have questions. As we aimed to keep the information sufficient, but minimal, we filtered out the most critical aspects of those shared values.
We also needed to find a way to make it easily accessible and updatable. Without having a proper habit of writing documentation or keeping it up to date, it is hard to motivate oneself. We found it most comfortable to include it as part of a development task. Including documentation as part of the definition of done seemed the most effortless. It helps to create a habit and make it a natural part of a task』s lifecycle. It helps to keep the documentation process agile. With little effort, we have a way to keep the information up to date and relevant without producing waste.
After several sessions, we finally had a template to include into our projects that were structured and is not some scary Documentation Monster to fill giving us a stepping stone to improve even more and see the importance of documentation well before when it is actually needed.
Key takeaways
Like in the agile world, we are still moving with the currents and improving the process, but we are in a lot better place than a while ago. Without dismissing the principles of agile methodology, we got to a documentation process that is lean and effective. It keeps its value by being updated when there』s a need for it.What we learned:
- Start writing handover documentation as early as possible
- When dealing with a small project, keep the documentation efficient and let it grow with the project.
- Keep writing documentation as part of issue』s definition of done rather than a separate task. This way you will have an agile documentation process
- Developing templates for certain types of documentation will make the process seem less scary.
下載開源日報APP：https://openingsource.org/2579/
加入我們：https://openingsource.org/about/join/
關注我們：https://openingsource.org/about/love/
