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

111–120 of 213 posts

Re: The Elephant at WWDC

#111

Post by lallysingh »

defaultname wrote: post #84
nextweek2 wrote: post #76

Earlier quoted context omitted.

> 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 "ho…

Nope. They've always had a lot of documentation. It's often been crap. I've been developing for MS platforms off and on since Win3.1, and have constantly dealt with cycles of "knowing API function A requires you understand what an X is, linked to function B, which only discusses X in terms of function A.". They write a lot, but it's not good. It's like a Hollywood western set where your at just the fronts of buildings. Lots of them, no depth.

You always have to get a 3rd party book to figure this crap out... if you can find one. And if you're off and on, then you're constantly playing this game every few years.

Frankly the X11 books out of O'Reilly are my standard for "good."

Re: The Elephant at WWDC

#112

Post by tayistay »

afavour wrote: post #97

This speaks to me. I’m not deeply involved in the iOS development world but I do a lot of webview-adjacent stuff so I keep a close eye on the WKWebView documentation. It’s a mess. Case in point: introduced in the new beta: loadSimulatedRequest: https://developer.apple.com/documentation/webkit/wkwebview/3... What does it do? Don’t know. I can make a few informed guesses from the name but I’m not sure if it’s maybe a p…

Sometimes you have to look in the headers. I don't know why it doesn't get parsed into the docs. Here's the documentation for loadSimulatedRequest:

  /*! @abstract Sets the webpage contents from the passed data as if it was the
  response to the supplied request. The request is never actually sent to the
  supplied URL, though loads of resources defined in the NSData object would
  be performed.
  @param request The request specifying the base URL and other loading details
  to be used while interpreting the supplied data object.
  @param response A response that is used to interpret the supplied data object.
  @param data The data to use as the contents of the webpage.
  @result A new navigation.
  */

Re: The Elephant at WWDC

#113

Post by amelius »

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…

Strangely, the best documentation I've seen so far has been PHP. The only reason: because developers could comment right below the documentation. It's like having StackOverflow right there, in the documentation page.

(Note: I haven't touched PHP since 20 years or so, so not sure if it's still the case).

Re: The Elephant at WWDC

#114

Post by wux »

moralestapia wrote: post #98
the-dude wrote: post #94

Earlier quoted context omitted.

And you couldn't be bothered to do a cursory search? > There's no place to find out what they are. Google worked fine for me. YMMV.

Could you please, then, point me to a creditable source regarding what 'powerd' is?

You can use the 'man' command in Terminal to pull up the man page (see: https://en.wikipedia.org/wiki/Man_page) for 'powerd' (that is, by typing 'man powerd'). By doing so, you'll see that it is a "launchd managed daemon" that "manages Energy Preferences."

Re: The Elephant at WWDC

#115

Post by runlevel1 »

xwdv wrote: post #26
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…

Disagree. The difference between professional technical documentation and something a “good coder” whipped up to explain some code is astounding. The skills to write good documentation approach something more resembling an English major than a programmer.

I think it's more about being able to see things from the audience's perspective.

It's hard to write good documentation without being able to visualize:

- What they know

- What they don't know

- What they're probably trying to accomplish

Some of the best API documentation comes in the form of examples, which doesn't draw much on writing skills.

That said, explaining high-level concepts/theory does require writing skills, but it also requires the skills described above.

Re: The Elephant at WWDC

#116

Post by stephencanon »

> have you ever heard of candidates for a software engineering post being selected by or for their ability to document their code?

FWIW, when I’m involved in hiring, I absolutely consider this a major factor.

Re: The Elephant at WWDC

#117

Post by auggierose »

hamiltont wrote: post #33

Passion comment: I'll second that most of Jonathan Levin’s books are outstanding, some of my favorite technical guides. Spent many years as senior dev for a custom Android ROM, yet Levin's book still introduced me to multiple other Android internals I had not yet looked into. Would happily pay 200-300 for his next Android book. Probably not the best books for a total beginner, but if you're already skilled and lookin…

Just tried to order the Levin books macOS/iOS books (wasn't even aware of them), but they don't ship to the UK ... Must be security restricted ...

Re: The Elephant at WWDC

#118

Post by merrywhether »

luckyorlame wrote: post #65

Writing code and writing documentation are completely linked, if you can’t do one, you probably can’t do the other.

Isn’t this a little like saying that because I can’t express myself well in Finnish, I probably can’t express myself well in English? Or maybe more like saying that writing about a topic and speaking about it are completely linked?

There’s a difference between having/understanding an idea and being able to express it in different modes/mediums of communication (in this case, to computers vs to humans). I’m not saying that one can’t learn to be better at a form of communication, but I recognize they are different abilities.

Re: The Elephant at WWDC

#120

Post by a_t48 »

dafelst wrote: post #110
gambiting wrote: post #92

Earlier quoted context omitted.

Yeah, xbox forums are very very good, and you usually get a reply directly from someone on the Xbox Development team within few hours. If you ever get a chance to go to XFest(assuming they still continue after the pandemic), it's really worth going - you get to meet people actually working on the hardware and software, collecting some of their emails goes a long way when working on a game ;-) And yes, PS4/PS5 documen…

Haha, yes, direct emails for folks in xbox is very useful, the xfest advice is very solid. I actually went from working at a first party studio inside Microsoft to an indie company, so luckily I have my network to fall back on. Now I just need to work out how to do the same for Sony and Nintendo...

There _used_ to be a Japanese game developers mixer at GDC (not sure if it's still around) - I met some folks from Nintendo there, though nobody specifically on the hardware side. Worth a shot, though. :)
Post reply on HN