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

11–20 of 213 posts

Re: The Elephant at WWDC

#11

Post by rleigh »

jtdev wrote: post #3
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…

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 greatly from. Writing code is only one part of the job, and writing documentation, requirements and design is a big part of the rest, and these parts are just as important. It's often the case that the act of writing down these things identifies inconsistencies and omissions which have not been picked up on during design or code review. And, ultimately, your libraries or application need to be used by other people, and if it isn't properly documented it's going to fall short of expectations since people won't be able to use it as intended.

Re: The Elephant at WWDC

#12

Post by nemetroid »

hug wrote: post #10
jtdev wrote: post #3

Earlier quoted context omitted.

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

I don't know why this is downvoted -- it's true. They are two very very different skillsets. I'm an ops guy, not a developer, and willing to hold my hand up and say that I suck at documentation. It's a deficit I recognise and work around: I have often paired up with someone who is better at documentation than I am, but less technically apt or possibly earlier on in their career than I am, because it's easier for me t…

I haven't downvoted any comment in this thread, but I think the parent post was a low-effort oneliner that didn't touch on the arguments made by the comment it responded to, and as such doesn't meaningfully add the conversation (even if it were correct).

Re: The Elephant at WWDC

#13

Post by thesuperbigfrog »

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…

Apple's issue is that unless the code is open source, the documentation is the only thing available to the "outside of Apple" audience.

If the documentation for the "outside of Apple" audience is not good enough without access to the source code, then developers feel it and the overall result is that Apple suffers as a platform.

Re: The Elephant at WWDC

#14

Post by brandonmenc »

I remember the documentation being pretty good up to and including OS X Tiger - back when Apple was still fighting for marketshare. I haven't tried to write anything for their platforms since then, specifically because the documentation is so poor.

I don't have time to track down a bunch of old WWDC videos and hope that they approach something like usable minimum developer documentation when combined. I start that process about once a year and every time throw my hands up in resignation. Life is too short.

Re: The Elephant at WWDC

#15

Post by zepto »

> First, it concentrates on documenting calls within an API by individual function.

Isn’t this just a misread of what DocC adds?

I watched the “Meet DocC documentation in XCode” wwdc session and the very first thing they talked about is how it complies Articles and Tutorials as well as reference documentation and how they can cross reference.

Re: The Elephant at WWDC

#16

Post by Grimm1 »

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 architected and implemented our full data infrastructure along with one other engineer. Which means I was responsible for high level conceptual documentation and low level documentation all the same and while I've written documentation before and for years I'm not formally trained in it so it was all still basically winging it. Since then I've actually taken a few short courses on writing better technical documentation since I felt it was a weak spot and having tools to assist in making that easier would have been great.

Documentation is hard and has been neglected but man does it have major underlying costs to getting it wrong.

Everything from on boarding being slow to misunderstandings that cause expensive bugs and everything in between. The root cause is developers have a hard time understanding complex systems and we as an industry are really hit and miss on writing the documentation that would make that understanding easier.

Re: The Elephant at WWDC

#17

Post by jeffreyrogers »

I've been playing around with Swift/SwiftUI recently and while the documentation is still unclear in some areas, it is significantly better than the documentation for their Objective-C APIs was a few years ago when I was trying to make an iPhone app.

Edit: Why is this downvoted? Do people really think the documentation got worse over the past few years?

Re: The Elephant at WWDC

#18

Post by bluenose69 »

leoc wrote: post #7

Wasn’t the original Inside Macintosh supposedly a nightmare? Did it improve dramatically over the lifetime of (classic) MacOS?

I thought it was very clear, and I kept it on my bookshelf long after it had become irrelevant. I only chucked it to make space for other things on the shelf.

Re: The Elephant at WWDC

#19

Post by millerm »

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…

+1 Nicely explained.

Re: The Elephant at WWDC

#20

Post by bluenose69 »

I just watched https://developer.apple.com/videos/play/wwdc2021/10166/ to learn about docC, and it looks pretty much like what folks have been doing in other languages for a long time.

For example R developers usually document functions, data, etc using Roxygen in-line comments and they use vignettes for tutorials and the like. An additional advantage of R is that it checks that the documented function arguments line up with the code function arguments (at least by name -- it has no way to judge whether what the developer makes sense, of course).

I'm not saying that this is not useful, because I think it is, very, useful. It's just that this seem more like catching up than leading, at least in the broad strokes.

Post reply on HN