今日推荐开源项目：《前人的经验 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://opensourcedaily.org/2579/
加入我们：https://opensourcedaily.org/about/join/
关注我们：https://opensourcedaily.org/about/love/