Read Me First!
Read Me First!

Author: Sun Technical Publications
Publisher: Prentice Hall, 3rd Ed, 2009
Pages: 464
ISBN: 978-0137058266
Aimed at: Technical writers
Rating: 4
Pros: A clear and consistent reference work for writers and editors
Cons: Don't look for amusement here
Reviewed by: Sue Gee

Has this style guide for the computer industry stood the test of time?

 

Author: Sun Technical Publications
Publisher: Prentice Hall, 3rd Ed, 2009
Pages: 464
ISBN: 978-0137058266
Aimed at: Technical writers
Rating: 4
Pros: A clear and consistent reference work for writers and editors
Cons: Don't look for amusement here
Reviewed by: Sue Gee

Nice application, let down by its documentation - does that sound familiar?

Many a developer would like to hand over the responsibility for writing words, as opposed to code, to someone else but that isn't always possible and in any case probably not a good idea as it can result in something that glosses over the technicalities.

 

Banner

 

Read Me First can help in more than one way - but for many users it's not the initial chapters that will be the most useful starting point. I would recommend new users to turn first to Chapter 3, Writing Style. this starts by asking "Why is style important" and goes on to recommend two stylistic principles:

  • Write simply, directly and accurately
  • Be consistent

Chapter 4 on Structuring Information is also well worth and early read. Chapter 10 Types of Technical Documents will help when you are not sure what you expected to write and Chapter 7, Writing Tasks, Procedures, and Steps will help anyone who is not sure how to go about writing instructions

Now we can return to Chapter 1, Mechanics of Writing,  which covers rules from capitalisation and contractions to through to use of punctuation marks. Chapter 2, Constructing Text, covers heading, lists, tables, cross-references and so on. It even mention code samples - and says to set them in a monospaced font.

There is a lot more practical advice - for example Chapter 6 on Constructing Links and also in the appendices. The book also has specialist information in  Chapter 9 on Legal Guidelines and Chapter 14 on Doocumenting Graphical User Interfaces. There are chapters on the role of the technical editor and working with an illustrator.

The first edition of the book came out in 1999 and this third edition keeps up with the times by including chapters on creating screencasts and using wikis for documentation. Another new chapter confronts the problem of creating alternative text for non-text elements such as screen captures, multimedia content, illustrations and diagrams.

If you are responsible for technical documentation this is a useful work of reference that will help you produce clear and consistent text for a wide range of publications.

Banner


ASP.NET 4.6 Web Programming with C# 2015

Author: Mary Delamater, Anne Boehm
Publisher: Murach
Pages:954
ISBN: 978-1890774950
Print:1890774952
Kindle: N/A
Audience: C# developers
Rating: 4.5
Reviewer: Kay Ewbank

This is a book designed for programmers who know C# and want to use ASP.NET web forms to develop server-side web applications.  [ ... ]



Beautiful Code: Leading Programmers Explain How They Think

Editors: Andy Oram and Greg Wilson
Publisher: O'Reilly, 2007
Pages: 618
ISBN: 978-0596510046
Print: 0596510047
Kindle: B0026OR2NG
Audience: Anyone who has an interest in programming
Rating: 4.5
Reviewer: Mike James

This collection of essays is approaching its 10th anniversary. It isn't [ ... ]


More Reviews

Last Updated ( Monday, 06 December 2010 )
 
 

   
Banner
RSS feed of book reviews only
I Programmer Book Reviews
RSS feed of all content
I Programmer Book Reviews
Copyright © 2018 i-programmer.info. All Rights Reserved.
Joomla! is Free Software released under the GNU/GPL License.