Re: Microsoft developer doc revamp

Subject: Re: Microsoft developer doc revamp
From: Andrew Harvie <withanie -at- gmail -dot- com>
To: TECHWR-L Writing <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 9 May 2016 16:12:23 -0300

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?

Totally aside... MS-DOS 5 manual? 3.3 was the last good one. ;)

On Fri, May 6, 2016 at 9:59 AM, Steve Hudson <sh1448291904 -at- gmail -dot- com> wrote:

> Indeed, for back in the 'bad ole days' of 'puting, no-one had a clue what
> this software stuff was. "A spreadsheet? Someone said it could help with my
> small business..."
>
> These days consumers are a lot more tech savvy and prepared to dig through
> menus and options to find stuff they know should be there. School leavers
> have had experience with a variety of packages (whether mandated by
> curricula, or just from casual life experiences.
>
> And of course, the moment that s/w dev stated "As little doco as possible"
> I
> lost all hope and semi-departed the scene.
>
> Steve
> Always the heretic (but know that most people don't really get that part)
>
> -----Original Message-----
> From: techwr-l-bounces+sh1448291904=gmail -dot- com -at- lists -dot- techwr-l -dot- com
> [mailto:techwr-l-bounces+sh1448291904=gmail -dot- com -at- lists -dot- techwr-l -dot- com] On
> Behalf Of Robert Lauriston
> Sent: Friday, 6 May 2016 0:30
> To: TECHWR-L Writing <techwr-l -at- lists -dot- techwr-l -dot- com>
> Subject: Re: Microsoft developer doc revamp
>
> I hung on to an MS-DOS 5? 6? manual for years because the command-line and
> batch file references were great. It was a model of organization and
> clarity.
>
> The Lotus 1-2-3 manuals from the same era (1990?) were also great, as were
> Adobe's circa 1995-2000.
>
> I think in those days manuals had to be good for software to sell well.
>
> On Thu, May 5, 2016 at 6:50 AM, Mike McCallister
> <mike -dot- mccallister -at- pkware -dot- com> wrote:
> > Got this link from a developer. Nothing in here about user docs, but
> success in one area can spread.
> >
> > http://arstechnica.com/information-technology/2016/05/microsoft-unveil
> > s-new-effort-to-make-its-developer-it-documentation-great-again/
> >
> > Some comments are valuable, in discussing the "golden age of Microsoft
> documentation," with pointers to the DOS docs. Curious to hear what others
> think about the state of Microsoft docs (dev and user).
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy and
> content development | http://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as sh1448291904 -at- gmail -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
>
>
> ---
> This email has been checked for viruses by Avast antivirus software.
> https://www.avast.com/antivirus
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy and
> content development | http://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as withanie -at- gmail -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
>



--

-- Andrew Harvie
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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


Follow-Ups:

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

Next by Author: RE: [RMX:NL] Re: [RMX:NL] Re: Request for comments on my Structured Writing series
Previous by Thread: RE: Microsoft developer doc revamp
Next by Thread: Re: Microsoft developer doc revamp


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


Sponsored Ads