今日推荐开源项目：《我当即写了两句诗 Chinese_poem_generator》
今日推荐英文原文：《How Much Documentation Do You Really Need?》
今日推荐开源项目：《我当即写了两句诗 Chinese_poem_generator》传送门：GitHub链接
推荐理由：有的时候我们需要一些藏头诗或者别的什么诗词，但是自己又没读过诗，这个项目就可以让你临时写一首诗了。通过诗词数据训练好一个模型之后，就可以让它来写一首看起来还挺像样的藏头诗了。不过尽管机器写出来的诗还有模有样，但是看过原理之后就会发现这并非是一种创意，而是对那些诗词进行模仿的成果——所以说你完全可以尝试着自己动手，兴许你的创意能弥补不足的知识量也说不定。
今日推荐英文原文：《How Much Documentation Do You Really Need?》作者：Aphinya Dechalert
原文链接：https://medium.com/better-programming/how-much-documentation-do-you-really-need-c7ccda9ab5f2
推荐理由：文档虽好，可不要贪多哦
How Much Documentation Do You Really Need?
When too much or too little becomes your Achilles heel
Documentation is often bundled into a statement of work (SoW) and becomes a necessary document that sits in with a contract. They are often produced by analysts, who consult with stakeholders and then often define with meticulous detail what the requirements, exact tasks, needs, and everything else in between are.At first, it seems logical to have such a document, mostly for verification and legal purposes. However, on a software development level, this methodology of documenting everything in such granular detail embeds the monolithic method of implementing a waterfall workflow.
This creates a rigid approach to software development that doesn’t give much room to respond to change or to enable developers to rapidly prototype a solution.
Requirements are often also one-sided and unvalidated, leaving the business more vulnerable to bigger failures — not because the developers haven’t delivered, but rather because the intended audience didn’t respond as expected to the software.
The Diminishing Returns of Over-Documentation
The more documentation you begin with, the more diminishing returns you are receiving in actual value. This is because the time it took to write the documentation prior to any development work is a sunk cost. There is nothing produced from it yet, nor is there any guarantee that the project will ever commence, either.The more documentation there is, the more time, resources, and money it takes away from other endeavors. The opportunity cost increases as the document becomes more detailed, reducing the business’s ability to be truly agile and to pivot to customer and market demands.
This is because the custom software is a solution based on pre-defined requirements, rather than one that is reflective of reality and true business needs.
Discovery of needs often comes during the development phase, and extensive documentation locks the business in on a contractual and financial level for something that may not end up being relevant.
When There Isn’t Any Document at All
For many businesses, especially those new to an agile approach to software development, the issue of finding the right balance of documentation can be a complicated task.However, there is a difference between not having any documentation versus indecision. If the business is clear with their values, goals and expected outcomes on a strategic scale, developers are able to produce prototyped solutions quickly. This allows the business to acid-test the investment against a consumer group.
When the business doesn’t have any documentation or a clear idea of what they’re looking for on a strategic level, it’s harder for developers to discern business rules required for the system. This often results in delays and a potentially flaky system because the business is unclear about what it wants, and therefore, developers cannot deliver a solution that is geared towards a specified problem.
The issue here is not due to the lack of documentation, but rather that the business is unable to communicate their needs and wants. This can be crippling to the software development process and poses a threat to delivery velocity — despite being on the opposite spectrum for documentation.
This is because documentation not written by developers is more a tool to clearly capture the wants and needs of the business, not to dictate to developers what they should be doing.
Balanced Approach with Living Documents
The idea of having living documents means that all parties involved in the software development process contribute to the externalization of knowledge.They are written by each group for a particular audience and is called a living document because of its activity. The initial documentation for the entire project creates an ideological scaffold for the software to fulfill. It is not prescriptive, nor is it overly descriptive. The living document aims to capture parts of knowledge that are not immediately obvious in the code.
This means that for certain audiences, more documentation will be required than others, and is based on relevancy only. For example, the business analyst is only expected to capture required business rules for backend developers to translate. Backend developers are expected to document their translations for their consumers, such as API documentation for frontend developers.
There is no single person or group that creates or maintains the process of documentation in isolation. When this happens, over-documentation in certain areas will often occur.
The best approach to documentation is to distribute the workload among different groups and only to document what is actually necessary. This will put less risk of falling into a waterfall method, while maintaining clarity for the business and their developers.
下载开源日报APP：https://openingsource.org/2579/
加入我们：https://openingsource.org/about/join/
关注我们：https://openingsource.org/about/love/
