Writer's Block
-
I love writing, and often get quite carried away once I get started, but right now I can't get started. I need to deliver some documentation for a reporting application I've just delivered. It includes some KPI reports, KPI 'master' data, and daily figures (and their totals), with capture and edit screens for all data. I'm stuck on my opening line, and I think once I get past that, I'll be cruising nicely. Here is is, please attack it and leave me some pieces to collage a better one with: The Nkomati Production KPI Reporting application provides production KPI reports on demand, and on schedule, and also facilitates the maintenance and capture of static and daily data that these reports are built on.
Ok, since most of the standard jokes have been covered, I'll chime in with some serious advice. I'm more comfortable writing fiction than documentation, but some of the same techniques apply. A sentence has to accomplish two things: Provide the necessary information, and sound good. If you feel silly reading it aloud, or are mentally saying "Blah blah blah" as you read part of it, then it needs work.
Brady Kelly wrote:
The Nkomati Production KPI Reporting application provides production KPI reports
Need a synonym there... Sure, it makes sense, but it sounds like "The input entry field is for input entry." I don't know what KPI stands for, but just partially-expanding that acronym might improve the sound of it. Anyway, here's my shot at it... The Nkomati Production KPI Reporting application is a data processing tool that provides both scheduled and on-demand reports, while also facilitating the maintenance and capture of the underlying data. Same facts, rearranged a bit, with less repetition. The "static and daily" part might be better in a subsequent sentence or paragraph.
Proud to have finally moved to the A-Ark. Which one are you in? Developer, Author (Guardians of Xen)
-
Ok, since most of the standard jokes have been covered, I'll chime in with some serious advice. I'm more comfortable writing fiction than documentation, but some of the same techniques apply. A sentence has to accomplish two things: Provide the necessary information, and sound good. If you feel silly reading it aloud, or are mentally saying "Blah blah blah" as you read part of it, then it needs work.
Brady Kelly wrote:
The Nkomati Production KPI Reporting application provides production KPI reports
Need a synonym there... Sure, it makes sense, but it sounds like "The input entry field is for input entry." I don't know what KPI stands for, but just partially-expanding that acronym might improve the sound of it. Anyway, here's my shot at it... The Nkomati Production KPI Reporting application is a data processing tool that provides both scheduled and on-demand reports, while also facilitating the maintenance and capture of the underlying data. Same facts, rearranged a bit, with less repetition. The "static and daily" part might be better in a subsequent sentence or paragraph.
Proud to have finally moved to the A-Ark. Which one are you in? Developer, Author (Guardians of Xen)
Ian Shlasko wrote:
I don't know what KPI stands for
Key Performance Indicators. I envy you for not knowing that.
Christian Graus Driven to the arms of OSX by Vista. Read my blog to find out how I've worked around bugs in Microsoft tools and frameworks.
-
John Simmons / outlaw programmer wrote:
grunting in delight
Grunting is what livestock do.
Christian Graus Driven to the arms of OSX by Vista. Read my blog to find out how I've worked around bugs in Microsoft tools and frameworks.
If she's grunting, she's visiting her animal side. Yummy...
.45 ACP - because shooting twice is just silly
-----
"Why don't you tie a kerosene-soaked rag around your ankles so the ants won't climb up and eat your candy ass..." - Dale Earnhardt, 1997
-----
"The staggering layers of obscenity in your statement make it a work of art on so many levels." - J. Jystad, 2001 -
I have a feeling the term 'static' is a little technical too. For users in the financial industry, would the terms 'fixed' (for static) and 'variable' (for daily or dynamic) work?
Software Zen:
delete this;Probably. They aren't old enough to be stuck on using the term Master Files. :~
-
Yes, but is anyone surprised ?
Christian Graus Driven to the arms of OSX by Vista. Read my blog to find out how I've worked around bugs in Microsoft tools and frameworks.
Not even me. I like a good explosion of comments, helpful or not.
-
Ok, since most of the standard jokes have been covered, I'll chime in with some serious advice. I'm more comfortable writing fiction than documentation, but some of the same techniques apply. A sentence has to accomplish two things: Provide the necessary information, and sound good. If you feel silly reading it aloud, or are mentally saying "Blah blah blah" as you read part of it, then it needs work.
Brady Kelly wrote:
The Nkomati Production KPI Reporting application provides production KPI reports
Need a synonym there... Sure, it makes sense, but it sounds like "The input entry field is for input entry." I don't know what KPI stands for, but just partially-expanding that acronym might improve the sound of it. Anyway, here's my shot at it... The Nkomati Production KPI Reporting application is a data processing tool that provides both scheduled and on-demand reports, while also facilitating the maintenance and capture of the underlying data. Same facts, rearranged a bit, with less repetition. The "static and daily" part might be better in a subsequent sentence or paragraph.
Proud to have finally moved to the A-Ark. Which one are you in? Developer, Author (Guardians of Xen)
Thanks, good advice and example. The target audience are all familiar with KPI though. It stands for Key Performance Indicator, and is a high level figure for management to assess the performance of e.g. a department, in a month. Different functional areas have different KPI's, e.g. a mine pit will have 'tons of ore hauled', where health and safety will have 'No. of incidents'.
-
Ian Shlasko wrote:
I don't know what KPI stands for
Key Performance Indicators. I envy you for not knowing that.
Christian Graus Driven to the arms of OSX by Vista. Read my blog to find out how I've worked around bugs in Microsoft tools and frameworks.
I've made an effort to stay out of management :)
Proud to have finally moved to the A-Ark. Which one are you in? Developer, Author (Guardians of Xen)
-
Thanks, good advice and example. The target audience are all familiar with KPI though. It stands for Key Performance Indicator, and is a high level figure for management to assess the performance of e.g. a department, in a month. Different functional areas have different KPI's, e.g. a mine pit will have 'tons of ore hauled', where health and safety will have 'No. of incidents'.
Gotcha. The point, though, is that you could take parts of that to make it read a little nicer... This is just about readability, not actual information... Instead of saying: "The Something KPI Report application produces KPI reports...", You could say: "The Something KPI Report application produces performance reports..."
Proud to have finally moved to the A-Ark. Which one are you in? Developer, Author (Guardians of Xen)
-
I love writing, and often get quite carried away once I get started, but right now I can't get started. I need to deliver some documentation for a reporting application I've just delivered. It includes some KPI reports, KPI 'master' data, and daily figures (and their totals), with capture and edit screens for all data. I'm stuck on my opening line, and I think once I get past that, I'll be cruising nicely. Here is is, please attack it and leave me some pieces to collage a better one with: The Nkomati Production KPI Reporting application provides production KPI reports on demand, and on schedule, and also facilitates the maintenance and capture of static and daily data that these reports are built on.
Brady Kelly wrote:
The Nkomati Production KPI Reporting application provides production KPI reports on demand, and on schedule, and also facilitates the maintenance and capture of static and daily data that these reports are built on.
Well, I think you've summarized so tightly there's nowhere left to go. <snip> how bout an intro: This document outlines the NPK reporting application and its capabilties for reporting and data capture of KPI information. Bit more, but not too much... The Nkomati Production KPI Reporting application provides both on demand and scheduled KPI production reports and includes data capture and maintenance facilities. right - now we split it out.... Data capture is implemented through an fully interoperable semi back end psuedo middle tier ATM cloud based plant wide fully replicated... {now the report part - standard (don't forget the screen shots) reports include... Reports can be customized with flavored syrup etc...} <snip>
-
Gary Wheeler wrote:
She breathed heavily, moaning in delight as he...
slowly took his long cable and plugged it into her Ethernet port. She gasped at the sight of his obvious technical prowess, while he ... Geekrotica
:..::. Douglas H. Troy ::..
Bad Astronomy |VCF|wxWidgets|WTLmodified on Wednesday, November 25, 2009 11:39 AM
... opened connection after connection to her very kernel. Soon, however, her firewall engaged, blocking his clumsy UDP advances. "You're going to need a better packet than that, Buster!" she threw at him, as his stack unwound.
Software Zen:
delete this; -
If she's grunting, she's visiting her animal side. Yummy...
.45 ACP - because shooting twice is just silly
-----
"Why don't you tie a kerosene-soaked rag around your ankles so the ants won't climb up and eat your candy ass..." - Dale Earnhardt, 1997
-----
"The staggering layers of obscenity in your statement make it a work of art on so many levels." - J. Jystad, 2001You Texans have an 'earthy' approach to things, don't you? :laugh:
Software Zen:
delete this; -
... opened connection after connection to her very kernel. Soon, however, her firewall engaged, blocking his clumsy UDP advances. "You're going to need a better packet than that, Buster!" she threw at him, as his stack unwound.
Software Zen:
delete this;:laugh: :laugh: :laugh: "As his stack unwound" - Vikram makes a mental note to use it.
Cheers, Vikram. (Cracked not one CCC, but two!)
-
Gotcha. The point, though, is that you could take parts of that to make it read a little nicer... This is just about readability, not actual information... Instead of saying: "The Something KPI Report application produces KPI reports...", You could say: "The Something KPI Report application produces performance reports..."
Proud to have finally moved to the A-Ark. Which one are you in? Developer, Author (Guardians of Xen)
Ah, I was slowing down a bit last night after shelving work in favour of beer. Thanks.
-
Brady Kelly wrote:
The Nkomati Production KPI Reporting application provides production KPI reports on demand, and on schedule, and also facilitates the maintenance and capture of static and daily data that these reports are built on.
Well, I think you've summarized so tightly there's nowhere left to go. <snip> how bout an intro: This document outlines the NPK reporting application and its capabilties for reporting and data capture of KPI information. Bit more, but not too much... The Nkomati Production KPI Reporting application provides both on demand and scheduled KPI production reports and includes data capture and maintenance facilities. right - now we split it out.... Data capture is implemented through an fully interoperable semi back end psuedo middle tier ATM cloud based plant wide fully replicated... {now the report part - standard (don't forget the screen shots) reports include... Reports can be customized with flavored syrup etc...} <snip>
Tim Deveaux wrote:
Data capture is implemented through an fully interoperable semi back end psuedo middle tier ATM cloud based plant wide fully replicated...
Brilliant! :laugh:
-
I love writing, and often get quite carried away once I get started, but right now I can't get started. I need to deliver some documentation for a reporting application I've just delivered. It includes some KPI reports, KPI 'master' data, and daily figures (and their totals), with capture and edit screens for all data. I'm stuck on my opening line, and I think once I get past that, I'll be cruising nicely. Here is is, please attack it and leave me some pieces to collage a better one with: The Nkomati Production KPI Reporting application provides production KPI reports on demand, and on schedule, and also facilitates the maintenance and capture of static and daily data that these reports are built on.
Brady Kelly wrote:
It includes some KPI reports, KPI 'master' data
KPI reports are so 2004, you better use TPS Report[^] now!
A train station is where the train stops. A bus station is where the bus stops. On my desk, I have a work station.... _________________________________________________________ My programs never have bugs, they just develop random features.
-
I love writing, and often get quite carried away once I get started, but right now I can't get started. I need to deliver some documentation for a reporting application I've just delivered. It includes some KPI reports, KPI 'master' data, and daily figures (and their totals), with capture and edit screens for all data. I'm stuck on my opening line, and I think once I get past that, I'll be cruising nicely. Here is is, please attack it and leave me some pieces to collage a better one with: The Nkomati Production KPI Reporting application provides production KPI reports on demand, and on schedule, and also facilitates the maintenance and capture of static and daily data that these reports are built on.
-
I love writing, and often get quite carried away once I get started, but right now I can't get started. I need to deliver some documentation for a reporting application I've just delivered. It includes some KPI reports, KPI 'master' data, and daily figures (and their totals), with capture and edit screens for all data. I'm stuck on my opening line, and I think once I get past that, I'll be cruising nicely. Here is is, please attack it and leave me some pieces to collage a better one with: The Nkomati Production KPI Reporting application provides production KPI reports on demand, and on schedule, and also facilitates the maintenance and capture of static and daily data that these reports are built on.
Hire someone from India or Pakistan through elance.com or guru.com for $100 to write it for you. Then just edit to your satisfaction.
-
Thanks, good advice and example. The target audience are all familiar with KPI though. It stands for Key Performance Indicator, and is a high level figure for management to assess the performance of e.g. a department, in a month. Different functional areas have different KPI's, e.g. a mine pit will have 'tons of ore hauled', where health and safety will have 'No. of incidents'.
A key point in technical writing is to not assume the reader knows what acronyms mean. Professional technical writing organizations recommend or require that acronyms be explained the first time it is used either in line or as a foot note. For example: The target audience are all familiar with Key Performance Indicator, (KPI) though. It may seem silly at first, but you would be surprised at how much clearer things become when there is a clear definition of terms.
-
I love writing, and often get quite carried away once I get started, but right now I can't get started. I need to deliver some documentation for a reporting application I've just delivered. It includes some KPI reports, KPI 'master' data, and daily figures (and their totals), with capture and edit screens for all data. I'm stuck on my opening line, and I think once I get past that, I'll be cruising nicely. Here is is, please attack it and leave me some pieces to collage a better one with: The Nkomati Production KPI Reporting application provides production KPI reports on demand, and on schedule, and also facilitates the maintenance and capture of static and daily data that these reports are built on.
Simple: consciously decide to write bad documentation first. Get going. Then go back and clean it up. Don't be afraid to have your first draft begin with a sentence that's leaden, cryptic, or awkward. When I do this, I often find that the "bad" version is much better than I thought it would be.
-
Simple: consciously decide to write bad documentation first. Get going. Then go back and clean it up. Don't be afraid to have your first draft begin with a sentence that's leaden, cryptic, or awkward. When I do this, I often find that the "bad" version is much better than I thought it would be.
Good advice. I've adopted the motto, "Progress before perfection", to help deal with my problem of not doing something not perfect, but it's an ongoing struggle to stick to it.