Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

The Elephant at WWDC

eclecticlight.co

Post reply on HN
Print view View original

81–90 of 213 posts

Re: The Elephant at WWDC

#81

Post by shadowfiend »

adambatkin wrote: post #9
m12k wrote: post #2

> That’s not why they code, nor are the skills of writing good documentation even vaguely similar to those for writing good code. Strong disagree on that one. Writing good code is all communication - with the computer, with your colleagues, with your future self who doesn't remember how or why you did something. It's written knowledge transfer. Blocks of code, just like paragraphs of documentation, need to both fit i…

No. Modern programming languages and frameworks are explicitly designed so that you don't need to see how your code fits into the whole. That's the whole point of building abstractions, because it's too hard to keep all of the details in your head at one time. Writing code is generally concerned with the low-level details, which are hidden from other parts of the system (and that's a good thing). When you ask someone…

No.

Modern day software strives to do this, but regularly falls short. To craft the abstraction correctly, you need to understand how it is to be used—this is its “whole”. The person writing the internals of the abstraction who does not understand the whole writes the internals poorly. They create a feature that breaks expectations. They optimize a code path whose unoptimized implementation is relied on for one reason or another. The consumer of the code who does not understand the reasoning for these low level implementations starts relying on sub-behaviors that aren’t actually intended. This is why even the low level folks need to understand the (proximate, at least) whole.

What you’re describing is the lazy programming strategy that is certainly easier but results in dependency stacks that are brittle. It means you can plug a junior developer in anywhere without a mentor, but it also means QA efforts are enormous or breakage frequent. In UIs, it’s how Apple can rewrite applications in a new framework and lose decades of system behaviors because no one fully understood the whole when they replaced the abstraction.

Abstractions are leaky. It is in their nature. Understanding or describing how they are meant to be used makes the leakiness a little more obvious, a little easier to understand. Any given team can choose to be lazy about this of course, and will export the costs to their code’s consumers.

The output of a single individual may lack this context, of course. That is why the best abstractions are often created by teams over time: it takes skill in both typing code and devising and describing architecture to create a good tool in the form of an abstraction. It takes those same skills to achieve continuity over time in maintaining a given framework, application, or other abstraction. Documentation is an assist to the tribal knowledge that helps support this continuity, and a way to export that knowledge to new people, and try to make it outlast the original designers if the abstraction.

Re: The Elephant at WWDC

#82

Post by LeSaucy »

nextweek2 wrote: post #76
defaultname wrote: post #44

Earlier quoted context omitted.

Microsoft has had superb documentation for decades. They put a lot of emphasis on it and the results show. The linked article is a bit off base, I think, because clearly Apple's documentation problem isn't a tool issue. It's a philosophy of documentation. I like going to the documentation for a critical system API class and finding all of the members, examples for each, and then "related" things. Philosophically Appl…

> Microsoft has had superb documentation for decades No, they've had lot's of documentation. That's not the same thing. For decades it was very shallow with no examples. You'd get an enum list with a half sentence explanation. The last couple of years they've really upped their game. With detailed examples, explanations and even source in multiple languages. To me Qt's documentation was the benchmark, but the latest…

Qt5 documentation quality has steadily slid down hill. Any new modules they add you essentially have to peruse the source to understand what/how/why it works.

Re: The Elephant at WWDC

#83

Post by smoldesu »

bob1029 wrote: post #30

Conversely, I have noticed that Microsoft has been kicking some serious ass in the documentation arena lately. If you haven't taken a look at their stuff in a while, you would probably be shocked. Here's a high level overview of GC to give you an idea of how thorough these documents are now: https://docs.microsoft.com/en-us/dotnet/standard/garbage-col... After reading through all of those sections, I will have develo…

I despise Microsoft's products for the most part, but I can't lie: their documentation kicks ass. The C++ documentation is some of the nicest around.

Re: The Elephant at WWDC

#84

Post by defaultname »

nextweek2 wrote: post #76
defaultname wrote: post #44

Earlier quoted context omitted.

Microsoft has had superb documentation for decades. They put a lot of emphasis on it and the results show. The linked article is a bit off base, I think, because clearly Apple's documentation problem isn't a tool issue. It's a philosophy of documentation. I like going to the documentation for a critical system API class and finding all of the members, examples for each, and then "related" things. Philosophically Appl…

> Microsoft has had superb documentation for decades No, they've had lot's of documentation. That's not the same thing. For decades it was very shallow with no examples. You'd get an enum list with a half sentence explanation. The last couple of years they've really upped their game. With detailed examples, explanations and even source in multiple languages. To me Qt's documentation was the benchmark, but the latest…

"No, they've had lot's of documentation. That's not the same thing. "

This kind of snotty reply is always interesting. I've been a professional developer for 25 years. For most of those years I was deep in the Microsoft platform. C++, Win32 API, DirectX, COM+/DCOM, OLE, automation, C# / .NET.

For decades they've had exhaustive narrative documentation that would give huge backgrounders on everything. Architectural "how it fits" documentation with wonderful diagrams, hierarchies, etc. I could easily find anything and jump to specific APIs. Shitloads of examples. They clearly have had a great documentation focus for a long, long time. Something like the MSDN Library was years before its time.

Let me repeat, probably with way more experience in saying this, that Microsoft has done documentation well for years, and I seldom felt deprived (aside from occasionally when they do a restructure and search engines/links go to obsolete links). It is specifically in contrast to Microsoft's long excellent documentation that I find Apple's to be a sad joke.

There is some bizarre tendency in here for people to pretend that everything Microsoft does well they've only done well for most recent history, as if this is some sort of odd proselytizing and naysayers should realize that everything has changed.

Re: The Elephant at WWDC

#85

Post by smoldesu »

valuearb wrote: post #59
traspler wrote: post #43

The way Apple talks about new developer features/systems seem like ads for very exclusive clubs sometimes. "If you are already doing this, you can do it here now and we show you some teases, talk to us if you want to know more". One example for me is ReplayKit... yes I don't know too much about Audio/Video but the little documentation there is it feels deliberately obfuscated and lacking. Better API level docs would…

New Kits are always tacked on, there are few overviews to tell you how an entire area works. I once spent days trying to update old AV player code get close captions working with Vimeo streams on iOS, half that time was just trying to understand how captions worked in AV streams at all. Every time something like AV gets a new set of APIs, Apple should update a detailed overview that explains we used to do things this…

> And I’m sick of watch videos. Give me a high level overview of the why and how of the managers, and in it link directly to detailed documentation pages, sample source code and pertinent WWDC videos so I don’t have to use my Google fu to figure out those links myself.

This is what I'm personally tired of. WWDC might actually be interesting if they focused on the developer...

Re: The Elephant at WWDC

#86

Post by Grimm1 »

spockz wrote: post #22
Grimm1 wrote: post #16

I think the reality is regardless of what we want, that at most companies the people who write docs are the people who write code. That doesn't mean it's the best way but it does make it the way we have to deal with a majority of time. That's why building tools to help engineers be better documenters from high level through to the low level is I think in the interest of everyone. In my last company before I jumped, I…

Can you please share the lessons learned in the courses about writing documentation or perhaps recommend some courses/materials? At my place we have an eternal struggle in “level”. We have some very high over docs, then ADR for specific decisions. At the lowest level we have the api documentation which we find most people don’t read. And then we have some tutorials. Every time I read our documentation it feels very i…

I think it may just be easier to share where I got any of my lessons from.

https://developers.google.com/tech-writing

Google has two short courses about 6 hours total or so that seemed a good consistent basis for me as an engineer writing documentation.

I'm not sure if it's going to answer your question on what types of documentation you will need though and how to make it feel less inadequate just how you as an individual can write better documentation.

Re: The Elephant at WWDC

#87

Post by lanstin »

rleigh wrote: post #11
jtdev wrote: post #3

Earlier quoted context omitted.

A good coder does not a good technical document writer make.

I disagree. If a programmer cannot articulate their thoughts and ideas clearly, and cannot effectively communicate with others through writing, I would question whether they fully understand the concepts themselves, and whether they are actually a good programmer. Being able to write is a skill in its own right, but it's one which anyone can acquire with practice, and it's one which many programmers would benefit gre…

I sort of think this except I had a job for several years where we had really good technical writers who would sit with various developer and produce far more accessible writing than I ever have.

It is valuable for my career to be able to write somewhat well but I am hired and earn my salary in other ways, debugging weird technical things; two days experiments, code reading, and maybe gdb and then one small PR and a short email explaining the issue. Write some nice network server to solve a network issue; implement some feature in a maintainable way. Etc. lot of work and mostly the way of thinking about it is a small piece of that work.

The tech writers made a small book that could be handed and/or emailed to people who then integrated with my API with no further interaction between me and them. It was very helpful.

Re: The Elephant at WWDC

#88

Post by Apocryphon »

defaultname wrote: post #44
bob1029 wrote: post #30

Conversely, I have noticed that Microsoft has been kicking some serious ass in the documentation arena lately. If you haven't taken a look at their stuff in a while, you would probably be shocked. Here's a high level overview of GC to give you an idea of how thorough these documents are now: https://docs.microsoft.com/en-us/dotnet/standard/garbage-col... After reading through all of those sections, I will have develo…

Microsoft has had superb documentation for decades. They put a lot of emphasis on it and the results show. The linked article is a bit off base, I think, because clearly Apple's documentation problem isn't a tool issue. It's a philosophy of documentation. I like going to the documentation for a critical system API class and finding all of the members, examples for each, and then "related" things. Philosophically Appl…

Embarrassingly, it's been said that Xamarin's iOS documentation is better than Apple's own.

Re: The Elephant at WWDC

#89

Post by Apocryphon »

jeremymcanally wrote: post #40

This post (while not wrong that the docs lack in a lot of areas) is written with apparent ignorance of how documentation is generated and published at Apple. Right now creating the code and docs are mostly decoupled. Having worked in the department where the docs are made, a tool like DocC is going to let the engineers who work on the code provide better docs to the Devpubs department so the authors there can stop wr…

Many teams at Apple are small but mighty and constantly overwhelmed. It speaks to the priorities of management to engender the existence of these situations. Or the sclerosis of the company culture.

Re: The Elephant at WWDC

#90

Post by lanstin »

mooreds wrote: post #56
mooreds wrote: post #36

I have loved documentation for a long long time[0]. In my mind, as the developer continues to drive technology decisions[1], documentation in all its forms will continue to be a differentiator on par with functionality. Developers are learning all the time because their job is changing regularly, and good/excellent documentation is a competitive advantage. w/r/t the article, I feel like engineers should write documen…

Incidentally, if you are looking for a mental model around tech documentation, I haven't found a better one than this: https://diataxis.fr/ which discusses tutorials, how-to guides, technical reference and explanation.

I always thought part of the reason node took off so quickly is that the intro docs all had a five line complete code example that was an http server. And when I wrote APIs for customers, I felt I could not do a good job in the API design unless I write an example that used the API, and then I had good sample code to share. I find all three things: conceptual framework “how to think about this API”, example code (with important error handling paths, just just postman collection), and thorough documentation on all the technical details are all important. Tho obviously the latter is done automatically now usually. But it is important to get out things like “I will return 429s and your code must have a good exponential back off/retry policies” to developers at the beginning.
Post reply on HN