Apple’s App Store review is strictly rigorous and everyone knows it. But writing code on Apple’s platform doesn’t seem to be a very enjoyable thing. The protagonist Chris Krycho is a front-end developer who bluntly stated that Apple’s developer documentation is junk. Why do you say this way?

Editor’s note: This article is from the micro-channel public number “InfoQ” (ID: infoqchina), Author: Tang Xiaozhi.

Apple’s AppStore review is strictly rigorous and everyone knows it. But writing code on Apple’s platform doesn’t seem to be a very enjoyable thing. The protagonist Chris Krycho is a front-end developer who bluntly stated that Apple’s developer documentation is junk. Why do you say this way?

1, Developer: Apple, your document is terrible!

ChrisKrycho has been working on JavaScript front-end development for the past five years. Over the past few months, he has struggled to keep up with the speed of the Apple Developer ecosystem and has made it all part of his rewrite project. (Note: rewrite is Chris’s personal project to build a cross-platform writing environment for academic research)

Chris has been learning Swift, SwiftUI, and iOS and macOSAPI. So he was shocked:

Frankly speaking, the low documentation integrity of the Apple ecosystem makes me feel uncomfortable.

As a front-end development using AngularJS and Ember.js, Chris said: Ember’s document quality is well understood. But in his four years of practical use, he witnessed Ember’s documentation from “smart to use” all the way to “quite perfect.” And AngularJS, Chris, who had been in contact with it five years ago, often collapsed: the documentation lacked an explanation of the core concept, or the explanation was unintelligible. He can only ask for help in despair, but others are usually in a state of Schrödinger’s understanding, between understanding or not understanding.

In my opinion, for large technology companies that open APIs, documents like Ember and AngularJS are a bad or even terrible state.

Unexpectedly, Chris is still too young.

Apple is the No.1 in terms of poor document quality, and any framework I touch can’t match it…

Chris at Apple PingThe feeling of Taiwan development is quite similar to the author’s work signature: EverydayStruggle.

In Chris’s view, Apple’s development platform and tools are also better for Swift. The documentation is of good quality and maintenance is relatively good.

But that’s it.

Most SwiftUI has no documentation at all, and there isn’t even a single line of code explaining the role of a given type or modifier. The documentation for SwiftPackageManager is pretty good, but it’s hard to see from the official documentation what it can do and what it can’t do. Many of Chris’s problems can only be solved for StackOverflow. He even has to read the texts of the WWDC conference repeatedly to see if anyone has mentioned the information about his current work.

He said that this situation is completely unreasonable:

In the Ember ecosystem, we have a simple rule that you can’t submit code unless you have documentation. The same is true of Rust (I was involved in the writing of the official strategy rfc). After personal contact, I realized that Apple’s API developers (usually) are not well aware of how open source projects work—perhaps because their delivery process involves more than just software, but more around hardware.

But in any case, as long as the API is exposed, development will only be completed if the corresponding documentation is published.

In Chris’s opinion, this pot can’t be deducted to a single software engineer, and the responsibility is no longer even a dedicated documentation team member. He believes that this is purely Apple’s failure in engineering organization. The people in the API engineering department are supporting the audience who use the API. Apple engineers definitely want to provide the corresponding documentation synchronously, but why not? Chris guessed that the team was seriously understaffed, or that Apple’s engineering culture simply did not pay attention to the documentation.

Apple claims to be interested in building a platform that everyone can use, including newcomers who are new to programming, and even older experts with decades of development experience. But until now, Apple has not really achieved this goal.

I have 10 years of software development experience, and most of the results are developed through a rich set of systems and functional programming languages. I have to admit that as a talented developer, many of them make me big and difficult to understand. I can’t even imagine the ecosystem that is directly facing Apple’s ecosystem for newcomers who are just starting to use development frameworks or have just touched mainstream languages ​​like Ruby, Python or JavaScript.There are still some problems with this method, be cautious)

3, how can I write a good design document?

The programmer’s attitude toward the document has a contradictory feeling. On the one hand, it depends on the document to obtain relevant development knowledge. On the other hand, few people are willing to write the document. Many people who are unwilling to write documents are not able to export their own development knowledge in a structured way.

Read documents and write documents, one input, one output, one reader, one author. To be a good programmer, having a good knowledge structure is extremely important. Try to write documents with structured thinking, and work in the present, and benefit in the future.

A good document should include requirements, design goals, system architecture, module introductions, potential risks, etc. The following points should be followed in writing:

  • Be as simple as possible;

  • Add a chart to visualize;

  • The number is more specific;

  • A certain amount of fun makes documents more readable;

  • Do a self-assessment and look at the documentation from the reviewer’s perspective;

  • Holiday test to see if others can read and implement;

  • The process is complete and key people are involved;