SCN Documentation Best Practices
Not everyone who writes content on the SCN is a technical writer. Thus, these best practices have been adapted from materials provided by TIP KM editors, Doug Savage and Dwight Anglehart, to help anyone who creates new content or works on existing content on the SCN.
10 Things to Keep in Mind
- Don't get too complicated. Say that difficult sentence out loud if you can't find the right words. Try to imagine how you would explain a concept in conversation. You can use technical language, but make sure it can be understood easily.
- Be helpful. Make sure you provide useful advice to the user. Give him something to do. Make him feel that he can take positive steps to resolve the issue. For example, you can use numbered steps to describe a procedure. Remember to cite your sources so others can do follow-up research.
- Avoid marketing language. If you are talking about product advantages or using terms such as "best-of-breed" or "real-time," you need to pare down your text. The user who needs help with using, implementing, or troubleshooting a product has already bought it.
- Write in complete sentences. For example, write The CMC takes a long time to display instances of a report object and may display an error message instead of CMC Performance fix.
- Don't use internal jargon. Although you may use technical terms in your daily work, these terms may make simple tasks seem difficult. For example, write caused an error instead of threw an error, and use install as a verb, not a noun. Spell out acronyms and product names the first time you mention them.
- Spell-check and proofread everything. A good way to do this is to paste the entire SCN draft into Word and run the spell-checker. You can also use a web browser (Chrome, Firefox) with a built-in spell-checker. Bad spelling makes our products look unprofessional and can signal that the writer doesn't know what he is talking about.
- Don't omit words. Remember your articles and prepositions. For example, write You can publish report to repository instead of You can publish report to repository. or You can publish report the repository.
- Practice consistent spelling. American spelling is the convention across SAP documentation. For example, write organize, not organise and color, not colour.
- Don't beg the user. There is no need to write please unless you ask the user to do something excessively complicated.
- Ask for help. If you get lost, you can refer to the SEO Cheat Sheet for SCN for basic guidelines on content and format. In addition (although the TIP KM documentation teams cannot be responsible for the entire content of the SCN) you can contact information developers such as Mike Khmelnitsky for particularly difficult cases of writing or usage.
10 Practical Examples
The following examples were taken from hotfix readme reports. The first column shows text written by the developer, exactly as it appeared in the report (along with typos and spelling and grammar mistakes). The second column shows the text edited by a technical writer.
|Original Text||Edited Text|
The issue is fixed
This problem is resolved.
In a Web Intelligence document having a cross tab, if the text in the uppermost left Corner cell of the cross tab is modified, then the text in that cell is getting truncated.
In a Web Intelligence document that uses a cross tab, if text in the first cell of the first column is modified the text becomes truncated.
In Russian language, canceling MAPI export or using an invalid e-mail address and checking name causes CRW32.exe crash.
In the Russian language version of Crystal Reports, either canceling a MAPI export, using an invalid e-mail address, or doing a name check may causeCrystal Reports to terminate unexpectedly.
After appling Java Runtime Environment 1.6.0 update 19 a security Warning is presented, if the 'Advanced Viewer' option is used to create or modify a Web Intelligence Document. If the option to block unsafe componentes is chosen, the table created is not viewable.
When the "Advanced Viewer" option is used to create or modify a Web Intelligence document, a security warning message may appear. This problem happens after the Java Runtime Environment 1.6.0 update 19 is applied. In addition, if the option to block unsafe components is selected, the table created cannot be viewed.
For a Desktop Intelligence document, if the universe is changedand report is then refreshed "Universe not found" error message is thrown.
For a Desktop Intelligence document, if the universe is modified, and then the report is refreshed, the following error message appears: "Universe not found".
"The parameter is incorrect." error occurs in Desktop Intelligence report when disable drill mode with mouse cursor in the filter text box.
In Desktop Intelligence, if a user places the cursor in the filter text box when the Drill Mode option is disabled, the following error message may appear: "The parameter is incorrect."
Desktop Intelligence reports refresh throws RCIRAS0546
When a Desktop Intelligence document is refreshed in InfoView, the following error message may appear: "Your request could not be completed because a failure occurred while the report was being processed. RCIRAS0546."
Desktop Intelligence core dump at ibtools.so`_1cMBOArrayULongJSetAtGrow6MlL_v+0x4
Desktop Intelligence documents may fail to open in InfoView, and then an error message appears.
A core dump happens at this line: ibtools.so`_1cMBOArrayULongJSetAtGrow6MlL_v+0x
[Regression] Custom Format get corrupted in Desktop Intelligence with Migration Forced option.
When custom formatting is applied to a cell in a Desktop Intelligence document, after the document is imported the cell contents are corrupted and incorrectly formatted. This problem happens when the option "Migration Forced" is enabled.
"Format Number" option was not being shown when opening a document migrated from XI R2 in WebI.
The "Format Number" option fails to appear in Web Intelligence documents that have been migrated from BusinessObjects Enterprise XI Release 2.
Variable based on DrillFilter() gives MULTIVALUE error in report table
When the drill function, DrillFilter(), is used on a variable that is based on another variable, the following error message appears: #MULTIVALUE.