Go Premium for a chance to win a PS4. Enter to Win

x

Technical Writing

276

Solutions

253

Contributors

Technical writing is any written form of writing or drafting technical communication used in a variety of technical and occupational fields, such as computer hardware and software, engineering, chemistry, aeronautics, robotics, finance, consumer electronics, and biotechnology. IT encompasses the largest sub-field within technical communication. The Society for Technical Communication defines technical communication as any form of communication that exhibits one or more of the following characteristics: "(1) communicating about technical or specialized topics, such as computer applications, medical procedures, or environmental regulations; (2) communicating through technology, such as web pages, help files, or social media sites; or (3) providing instructions about how to do something, regardless of the task's technical nature".

Share tech news, updates, or what's on your mind.

Sign up to Post

A big percent of today’s marketing activity is performed through the online environment. The marketing strategies that have existed a decade ago no longer relate to what’s happening today. We’re currently facing a revolutionary era, called the digital era. In ten years, the technology has developed
0
Industry Leaders: We Want Your Opinion!
Industry Leaders: We Want Your Opinion!

We value your feedback.

Take our survey and automatically be enter to win anyone of the following:
Yeti Cooler, Amazon eGift Card, and Movie eGift Card!

Read about how to approach blogging and about ways to do it right. Stand out from the crowd and let your knowledge be consumed by a large audience. This article aims to explain how your blog should look like,  the most important things to do while building it, and how to connect with other experts.
2
This is an article on how to answer questions, earn points and become an expert.
17
 
LVL 21

Expert Comment

by:Ramin
Comment Utility
It was very useful for me, thanks for sharing your experiences.
0
 
LVL 99

Author Comment

by:John Hurst
Comment Utility
You are most welcome and I am pleased the article was useful to you.
0
Rock and Roll Lifestyle
How to write articles for greater odds of being published and maximum points.
35
 
LVL 7

Expert Comment

by:Yashwant Vishwakarma
Comment Utility
Great one, will apply these tips to make my article rockstar !!!
Voted Yes :)
Thanks Jim :)
0
 
LVL 7

Expert Comment

by:jorge diaz
Comment Utility
Thanks Jim,

Very helpful article.
0
Here's a quick and dirty way to create an custom image from a screenshot for use in Experts Exchange questions, articles, or any document using a Windows PC that does not require installing extra software, and creates a compact image of what you wish to display that does not show any unneeded back
6
 
LVL 30

Expert Comment

by:Thomas Zucker-Scharff
Comment Utility
Nice article Jim.
0

This article is a requirements document template for a reporting project, based on my development experience as an SSRS, Crystal Reports, and Access developer over the years.  


For a Requirements Document Template for an ETL Project see my article here


After enough trial and error from the best and worst clients, business analysts, executive sponsors, and my own shining and less-than-shining moments I have seen many developers confronted with poor requirements turn into ... the DEV Nazi!!


The DEV NaziSo to make sure that doesn't happen to you, here's a template for your reporting projects.


In scope for this article

  • A requirements doc template designed for business analysts to cover most reporting projects.
  • Witty advice


Out of scope for this article

(But maybe if you vote Yes and comment nicely at the bottom of this article I'll write another article on it.)

  • Requirements Elicitation
  • Requirements documents specific to other types of projects, such as ETL and Data Warehousing
  • Report Design, especially the new minimalist style that's gaining popularity

So here we go..


Version History

A 'who changed what when' chronology of all changes, either using Word change tracking or lines like 'Bob's changes in yellow highlight'.  Keeps everyone honest when there are lots of changes.


Purpose

Also known as project objective, business goals, business problem statement, and various other terms.

A simple 'Here's why we're doing this' paragraph.  The target audience being those that are likely to only read this paragraph, but this also gives the developer some design decision guidance.


In Scope / Out of Scope

Everybody LOVES this section!  Okay, developers LOVE this section.  In Scope is a summary of what's in the requirements.  Out of Scope is usually a Top 10 list of things that are close but not in, and answers the often asked question 'Are we also getting this too?'  This is a developer’s best line of defense against scope creep by false or unstated expectations. 


And yes, just because person x told person y a month ago that it’s in requirements, or this email two months ago said it’s in, or was mentioned on the golf course last year during preliminary negotiations means that it’s in.   I've also known more than a couple of clients that will negotiate effort, cost, and time, and then scope creep the hell out of a project in order to make themselves look better.  Been there, dealt with that. 


grumpy-cat-out-of-scope.jpg

Schedule

A statement on when this can be completed, such as 'When division X is in the data warehouse', 'When project ABC is completed', 'Beginning in FY 2013', 'Yesterday', etc.  Helps project managers plan this project within a project management system that deals with all projects, all resources, and available time.


Report properties

  • Name - The name people will call it.
  • Description - 25 words or less.
  • Population - “All x's by y for time period z-1 to z-2”.  Also note if report values are supposed to match any other report.
  • Business Owner(s) - The person that will approve the creation of the report, and likely any future changes.
  • Technical Owner(s) - The person that will build the report, and likely any future changes.
  • Is there a Service Level Agreement (SLA)? - This will dictate how much effort will be done to log report success/failure, does this warrant somebody getting a phone call at two in the morning to fix it, and how many resources should be thrown to break/fix it.
  • Style sheet / cosmetics to use - Usually in the form of 'make this look like..'
  • Exact source of data if known, and if it matters.
  • Page count - Does it absolutely, positively have to fit on one page?
  • Does this report need to be historically reproducable? - If your data is frequently updated or deleted, re-running a report for a prior period may not result in the same exact report as when it was originally ran.
  • Availability - Once a day at 8am, 24/7, etc.
  • Accessibility - How will it be accessed?  Internally, externally, on a boat, with a goat...
  • User Security - Who can view the report.
  • Data Security - Does it contain Personal Health Information (PHI) or Personal Identity Information (PII) that would require protection?
  • Does anything get turned off once this report is placed in production?


Parameters

  • User supplied values that will change the population.  For each parameter
  • Name as it would appear on the screen
  • Format - Number, date, text, etc.  Also is it free-form text, or populated from a range of values?
  • Cascading - Are parameter 2 values dependent on what is selected in parameter 1?
  • Should an ‘All’ option be added?
  • Can users select multiple values?
  • User security - Does any of the above require users to have access to only a specific set of parameters, such as the Seattle boss can only run it for Seattle?
  • Time period - Will this report ever need to be run for a specific date or range of dates?

 

Header

  • Will usually be dictated by style.  Frequent header items are the company logo, formal name, report number if it exists, and any parameters that were used to generate the report.

 

Detail

For each section

  • How is it populated - Especially if sections are populated differently.
  • Drill down - Click or mouse over something and details either appear below it
  • Grouping, including header and footer info.
  • Sorting - Default sort order, which columns are sortable, and any special sort order other than 0-9 or A-Z.
  • Links to other reports - If there are multiple reports and links between them, a map is an excellent idea. Each ‘other report’ would require its own requirements doc.
  • Alternating background color - Makes the report easier to read.


For each column

  • Name
  • How populated - Single value, a defined calculation such as 'Beginning inventory for the month + Purchases - Sales'
Fun fact:  Providing a PowerPoint presentation from some VP and saying 'these numbers are just to illustrate the concept' is not a good requirement for a calculated column. Trust me on this one.
  • Data Type - Numeric, Currency, Date, Text.  Also other formatting info such as decimal places, dollar sign, thousands separators, and negative number handling.
  • Borders - Around all cells, none, heavy borders on certain sections.
  • Conditional Formatting - Make the color of bad stuff red, good stuff green, etc.


Does any part of the report have to match other parts of the same report?  (i.e. Sum of Dollar Amount matches ‘Grand Total’ text box)


Footer

  • Will usually be dictated by style.  Frequent footer items include page number, date/time of generation, and a legal notice.


Execution

Automated Execution

  • Time period - Mmonthly, daily, immediately after another process completes
  • Delivery method - Email, Excel, etc.
  • Distribution List - Who gets the report?
  • Data Security - Does the report need to be encrypted/decrypted?


Manual Execution

  • Where does the user go to execute it?


Archival

  • Are reports archived - Where, and for how long…
  • If yes, is there a reason why - SOX, ISO 9000, CIA, Company Policy, etc.


Are requirements easily understood?

Any confusion in requirements is going to be defined differenty by different people, resulting in time and effort, and goodwill if that confusion is between you and the client. 


unclear-business-requirements-or-scope-c

A big honkin' list of other quantifiable things you may need to directly address

Availability, Capacity, Data Currency, Data Retention, Degradation, Deployability, Exception handling, Extensibility (flexibility), Internationalization, Interoperability, Audit logs, Maintainability, Portability, Privacy, Recoverability, Reliability, Response time, Scalability, Security, Upgradeability, Usability.


NOT to be confused with these MBA Buzzword Bingo words, which may sound real impressive but have no quantifiable characteristics whatsoever:


World-class, best of class, best of breed, industry leading, empowerment, collaboration, repurpose, frictionless, client-focused, ecosystem, excellence, synergize, geo-targeted, diverse, environment, core competency...


dilbert-buzzword-bingo.jpg


And finally :: drum roll ::  Top 10 tips for writing requirements docs...


10   If requirements documents were easy, they'd offshore both the requirements and development for a third of what you cost, so don't get bent out of shape when things are complicated.  It's job security.

9      Never underestimate the awesome power of a :: blank stare :: to get people to provide you with better requirements

8      Sometimes 'draw me a sketch' is an excellent place to start requirements elicitation.

7      Never assume customers know exactly what they want.  Sometimes you have to guide them to the answer.

“If I had asked people what they wanted, they would have said faster horses.” - Henry Ford

6     Scope Creep - Changes in requirements after the initial ones are approved, but there cannot be an expectation that they will be immediately accepted.  They must be managed with budget, schedule, and resources.

5      Make sure the right stakeholders are defined, included in requirements elicitation, and accountable.

4      You are not an order taker!  (see 'Faster Horses' above).  This means you have to own your expertise and discover your customers needs together

3      Being a Business Analyst is its own career track, with its own training and certification.  The IIBA has plenty of resources.

2      Requirements documents should be signed by all customers.  In blood would be preferable, but in modern times ink is an acceptable alternative. ... and the number one tip for writing requirements docs...

1      Any requirement that is missed, and caught in later stages of development, will cost WAY more money to fix, so make sure you get it all!!


Thank you for reading my article, please leave valuable feedback. If you liked this article and would like to see more, please click the Good Article button near the bottom of this article.  


I look forward to hearing from you. -  Jim  ( LinkedIn )  ( Twitter )


The material in this article was presented at SQL Saturday #682, St. Paul Minnesota, 2017.


22
 
LVL 8

Expert Comment

by:Senior IT System Engineer
Comment Utility
Thanks for sharing !
0
 

Expert Comment

by:David Reeves
Comment Utility
Beautiful article!  Thanks so much!  Now turn it into a beautiful spreadsheet...
0

Technical Writing

276

Solutions

253

Contributors

Technical writing is any written form of writing or drafting technical communication used in a variety of technical and occupational fields, such as computer hardware and software, engineering, chemistry, aeronautics, robotics, finance, consumer electronics, and biotechnology. IT encompasses the largest sub-field within technical communication. The Society for Technical Communication defines technical communication as any form of communication that exhibits one or more of the following characteristics: "(1) communicating about technical or specialized topics, such as computer applications, medical procedures, or environmental regulations; (2) communicating through technology, such as web pages, help files, or social media sites; or (3) providing instructions about how to do something, regardless of the task's technical nature".

Top Experts In
Technical Writing
<
Monthly
>