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

21–30 of 213 posts

Re: The Elephant at WWDC

#21

Post by woutgaze »

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 recommend a book or course for improving ones ability to write good technical documentation?

Re: The Elephant at WWDC

#22

Post by spockz »

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 inadequate of conveying all our knowledge and intentions.

Re: The Elephant at WWDC

#23

Post by duped »

throw14082020 wrote: post #4

this article is saying how Apple DocC (the new documentation compiler revealed at WWDC 2021 this week) is not going to solve the problems Apple (and their developers) face. It has interesting examples. I think it will make documentation better, not because DocC is the perfect solution, but because it re-emphasises the importance of documentation because its new. It also gives developers at Apple a standard tool, was…

You could run Doxygen on the header files in /Library/Developer and it would give you something decent that didn't strip the doc comments.

Re: The Elephant at WWDC

#24

Post by JimDabell »

bluenose69 wrote: post #20

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…

> it looks pretty much like what folks have been doing in other languages for a long time.

It looks pretty much like what folks have been doing in Swift for a very long time. DocC is just Apple’s own version of Jazzy / SwiftDoc / appledoc. There’s no catchup here, it’s just Apple making an “official” version of something that already exists.

Re: The Elephant at WWDC

#25

Post by rubicon33 »

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…

> Anyway, the higher-level documentation is a very different style of writing. It needs to read like a book

Totally agree. When I need to learn a new subject like Core Audio or something I get a book.

Re: The Elephant at WWDC

#26

Post by xwdv »

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.

Re: The Elephant at WWDC

#27

Post by cromka »

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…

Very eloquently said, couldn’t agree more.

Re: The Elephant at WWDC

#28

Post by codys »

throw14082020 wrote: post #4

this article is saying how Apple DocC (the new documentation compiler revealed at WWDC 2021 this week) is not going to solve the problems Apple (and their developers) face. It has interesting examples. I think it will make documentation better, not because DocC is the perfect solution, but because it re-emphasises the importance of documentation because its new. It also gives developers at Apple a standard tool, was…

The general apple documentation for functions, etc appears to be pretty much a customized doxygen. One can see this by reading the header files for some of their frameworks and noting the doxygen comments there match up with their web-published documentation exactly.

That said: some folks didn't really get the memo, because there are important details that are sometimes included in non-doxygen comments in Apple's headers and thus aren't reproduced into Apple's generated/published docs.

In particular, the headers (sometimes) include annotations for specific types included in CF containers for return values.

Re: The Elephant at WWDC

#29

Post by JimDabell »

throw14082020 wrote: post #4

this article is saying how Apple DocC (the new documentation compiler revealed at WWDC 2021 this week) is not going to solve the problems Apple (and their developers) face. It has interesting examples. I think it will make documentation better, not because DocC is the perfect solution, but because it re-emphasises the importance of documentation because its new. It also gives developers at Apple a standard tool, was…

> It also gives developers at Apple a standard tool, was there such a thing before?.

Yes, Jazzy, SwiftDoc, and appledoc already do this, plus whatever in-house tool that already existed at Apple before this (they have clearly been using something like this for the past ~15 years).

Re: The Elephant at WWDC

#30

Post by bob1029 »

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 developed a very strong understanding for how GC works in .NET and how I should strategically approach it for certain types of problems. I would also have clear, specific code examples to follow as appropriate.

The best thing for me is that when I click the "Edit" button on Microsoft's documentation, it takes me directly to the latest markdown source file on GitHub and I can immediately submit a PR for corrections or enhancements. Good luck doing something even remotely like this with Apple.

Post reply on HN