今日推薦開源項目：《我當即寫了兩句詩 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/
