Introducing docs.microsoft.com • Hacker News Board

Re: Introducing docs.microsoft.com

#191

Post by anarazel » Thu, May 05, 2016, 1:46 AM UTC

jrapdx3 wrote: post #189

krylon wrote: post #150

Earlier quoted context omitted.

It's not just the builtin search, the way the content is organized always seem be out of line with the way my brain works. As a reference, take a look at (if you're not familiar with it already) at PostgreSQL's manual[1]. With Postgres, I don't need to search, I can (nearly always) find what I need by scanning the table of contents by eyeball. Also, I can download the whole thing as a PDF for offline reading (or prin…

Couldn't agree more. I've always considered PostgresQL's documentation the finest of any software I've used, OSS or not. Many years' experience with all kinds of software convinces me it's nearly a law of nature: the quality of a project's documentation predicts the quality of the software itself. However I'm pretty sure writing excellent documentation must be a very hard task, otherwise it wouldn't be such a rarity.…

I think postgres' docs work quite well as a reference documentation. But in my opinion they're quite bad at introducing users to postgres/SQL/databases, including important operational tasks like backups.

Re: Introducing docs.microsoft.com

#192

Post by Navarajan » Thu, May 05, 2016, 9:32 AM UTC

reminds me docs.google.com

I thought it as a canonical pointer for Office 365 docs.

Re: Introducing docs.microsoft.com

#193

Post by Raphmedia » Thu, May 05, 2016, 1:29 PM UTC

pinouchon wrote: post #134

Raphmedia wrote: post #129

Earlier quoted context omitted.

Hold the button while you read, the popup appears on mouse button up and not on the press itself.

No

It does for me anyway, must depend on browser and device.

Re: Introducing docs.microsoft.com

#194

Post by xcrunner529 » Thu, May 05, 2016, 4:29 PM UTC

danfernandez wrote: post #166

zx2c4 wrote: post #2

From TFA: "Shortened Article Length Another common piece of feedback was that our content at times can be overwhelming because of its length and that long articles are more difficult to navigate and find what you’re looking for. To address this, we’ve broken down many longer articles into smaller logical steps and provided Previous and Next buttons at the bottom of articles to navigate between steps in a multi-part t…

[Disclosure: I work for the team that built docs.microsoft.com] Thanks for the feedback, and we went through a lot of customer feedback already on this. I'll try to be brief in a response - A good example on why - For our documentation we clearly saw customers jumping around content trying to find the part of the article that helps them. Depending on the article (see point #2) very few people read from beginning to e…

How about building in a direct way to report errors and issues with the docs that actually is fixed and checked? You can't even get a working MIM 2016 AD sync setup right now with the numerous errors in your docs (https://docs.microsoft.com/en-us/microsoft-identity-manager/...).

It's frustrating to say the least and I'd prefer we not even deploy the product.

Re: Introducing docs.microsoft.com

#195

Post by jrapdx3 » Fri, May 06, 2016, 5:41 AM UTC

anarazel wrote: post #191

jrapdx3 wrote: post #189

Earlier quoted context omitted.

Couldn't agree more. I've always considered PostgresQL's documentation the finest of any software I've used, OSS or not. Many years' experience with all kinds of software convinces me it's nearly a law of nature: the quality of a project's documentation predicts the quality of the software itself. However I'm pretty sure writing excellent documentation must be a very hard task, otherwise it wouldn't be such a rarity.…

I think postgres' docs work quite well as a reference documentation. But in my opinion they're quite bad at introducing users to postgres/SQL/databases, including important operational tasks like backups.

In some respects that's true, though the docs do contain a lot of patient explanation at a pretty basic level.

I wouldn't exactly call it a tutorial but it did teach me a great deal about SQL when I started using the db > 15 years ago.

New standards and features have made the program more complicated over time, so periodically I need to study up on these topics. More than a few times, it's been really useful to have that "beginner level" info re: stuff that's new to me.

But like you say, not all subjects are covered that way, perhaps they haven't been considered to be basic. I bet if there are enough requests the project would improve the documentation in those areas.