Re: Microsoft developer doc revamp

Subject: Re: Microsoft developer doc revamp
From: Robert Lauriston <robert -at- lauriston -dot- com>
To: TECHWR-L Writing <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 9 May 2016 13:34:05 -0700

There are few doc design errors worse than collapsed text that doesn't
turn up in an in-page search.

Clicking a link to continue reading is standard in lots of contexts.
Offering several such links if there's more than one possible
successor seems absolutely standard to me. Conceptual topics such as
the one in the example often are logical prefaces to many procedural
topics.

"... does every paragraph really need to have it's own comments
thread?" It doesn't. The comments are in the page footer.

I see they're using Livefyre for that. Anybody have experience with it?

On Mon, May 9, 2016 at 12:12 PM, Andrew Harvie <withanie -at- gmail -dot- com> wrote:
> They seem to be doing several things well, but mostly it's about making the
> documentation page easy to read.
> https://docs.microsoft.com/teamblog/introducing-docs-microsoft-com/
>
> I mostly like the idea of having the url match the header.
> I find it interesting that they plan to break up longer articles into
> smaller ones. I thought the in-thing was scrolling over clicking.
> Going back to the sample site where Intune is documented, I'm not at all
> keen on the "In this article" links that boot you to a section at the
> bottom of the page. I know that there are folks here who dislike expanding
> sections, but isn't this worse?
> And, does every paragraph really need to have it's own comments thread?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


References:
Microsoft developer doc revamp: From: Mike McCallister
Re: Microsoft developer doc revamp: From: Robert Lauriston
RE: Microsoft developer doc revamp: From: Steve Hudson
Re: Microsoft developer doc revamp: From: Andrew Harvie

Previous by Author: Re: LinkedIn job listings - any tweaks available for bettersuggestions ?
Next by Author: Re: LinkedIn job listings - any tweaks available for bettersuggestions ?
Previous by Thread: Re: Microsoft developer doc revamp
Next by Thread: How to Refer to Software Versions ?


What this post helpful? Share it with friends and colleagues:

Sponsored Ads


Sponsored Ads