How We Write and Format Script DescriptionsThis idea shows the published result of the example script description used in our How PineCoders Write and Format Script Descriptions page available on our website, where you can see the marked up text used to format the description. Some of the techniques we use are described right here, in this description, but more information is available from the website.
═════════════════════════════════════════════════════════════════════════
█ OVERVIEW
We begin our descriptions with an "Overview" section, keeping in mind that these first sentences will appear in the widget of the published script. The widget is the small thumbnail representing your script in the Scripts stream or in your user profile's "Scripts" tab. When users click on your script's widget , they open your script's page .
█ CONCEPTS
Besides plain paragraphs of body text like this one, sections can contain:
Numbered lists
We placed an empty line before this sub-section and used bold type for its header. Numbered lists work well for instructions divided into steps, or for lists introduced by specifying a finite number of elements. This numbered list contains three items:
1 — We use a number + space + Em dash + space to prefix items. As we do for bulleted lists, we manually break long elements into individual lines shorter than a script page's width so we can indent the item correctly. Otherwise it would appear like this one, which is inelegant and makes the list more difficult to read.
2 — This is a properly broken element. We try to break items after a sentence or a comma. If that's not possible, we break sentences where pauses will affect legibility the least.
You will often need to preview an element's text to determine which lines require manual breaks, as the editing window may have any width.
We prefix lines following the first one with two Em spaces in order for them to align correctly, as is done with this line, the previous and the following ones.
This makes the next items easier to read. Try to make the last line of multiple line elements the shortest.
3 — This element is easier to read because the previous lines are indented.
Bulleted lists
Bulleted lists work the same way as numbered lists, except that:
• They are prefixed with Em space + bullet + space.
• When an item requires its lines to be broken manually, we indent the lines after the first one with two Em spaces.
Second line introducing an indented bulleted list:
• First line of second bulleted list which is prefixed with three Em spaces. This first item is too long and will require manual line breaking.
We prefix this second line with four Em spaces.
• Second item.
• Last item of our bulleted list.
Sub-sections containing one or more paragraphs
At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis praesentium voluptatum deleniti atque corrupti quos dolores et quas molestias excepturi sint occaecati cupiditate non provident, similique sunt in culpa qui officia deserunt mollitia animi, id est laborum et dolorum fuga. Et harum quidem rerum facilis est et expedita distinctio. Nam libero tempore, cum soluta nobis est eligendi optio cumque nihil impedit quo minus id quod maxime placeat facere possimus, omnis voluptas assumenda est, omnis dolor repellendus.
Temporibus autem quibusdam et aut officiis debitis aut rerum necessitatibus saepe eveniet ut et voluptates repudiandae sint et molestiae non recusandae. Itaque earum rerum hic tenetur a sapiente delectus, ut aut reiciendis voluptatibus maiores alias consequatur aut perferendis doloribus asperiores repellat.
█ OTHER SECTIONS
These are some common other types of sections we use, as needed. Keep section titles short:
• FEATURES: to describe the detailed features of the script, usually arranged in the same order as users will find them in the script's inputs.
• HOW TO USE
• LIMITATIONS: where we mention any shortcomings of our script, such as that it plots using offsets into the past, or doesn't work on certain types of charts,
or is less reliable in certain market conditions, for example.
• RAMBLINGS: where we discuss points of view or hypotheses.
• NOTES
• THANKS: where we credit authors who have provided either code or inspiration for our work. We will often mention authors by using a hyperlink to their scripts page,
as when we thank the Maestro, RicardoSantos .
═════════════════════════════════════════════════════════════════════════
A clear separation between major parts of your description can be indicated by several empty lines above and below a line made of the double-line character, U+2550 (═), which renders without gaps in the Trebuchet font TradingView uses.
Description*
Making A Good Indicator DescriptionIntroduction
When posting an indicator a good concept/code isn't the only thing required in order to have a quality indicator, its description is also extremely important. Each person has its own style,
mine is pretty academic, but as long as your description respect certain criterions you are free to do as you wish.
In this post i want to help you make the best of your published indicator by introducing basic concepts in post writing.
Basic Description
An indicator description should at least explain what kind of information your indicator is giving as well as how to interpret/use it. Lets take the Supertrend indicator as example, we'll be making a brief description of it.
The Supertrend indicator is a technical indicator created by the french trader Olivier Seban that aim to detect the current market trend direction. The indicator detect an up-trend when below the market price and a down-trend when above.
This indicator posses two setting, length and mult, higher values of length/mult allow the indicator to detect trends of longer period. This indicator can also be used as trailing stop loss, it can also provide a support level when below the price or a resistance level when above.
Lets breakdown this simple description.
-"The Supertrend indicator is a technical indicator created by the french trader Olivier Seban"
If the indicator is not yours, always credit/mention the original author, this is no option.
-"that aim to detect the current market trend direction"
Aim of the indicator.
-"The indicator detect an up-trending market when below the market price and a down-trend when above."
How to interpret the indicator.
-"This indicator posses two setting, length and mult, higher values of length/mult allow the indicator to detect trends of longer period."
Always try to introduce the indicator settings and explain how they affect the indicator output.
-"This indicator can also be used as trailing stop loss, it can also provide a support level when below the price or a resistance level when above."
Alternative uses of the indicator, try to provide a graphic showing the indicator acting as mentioned, i our case we should show a graphic showing the Supertrend acting as a support/resistance.
Once you write up your indicator description read it back several times (something i wish i could do more often) and always ask yourself if your indicator description fully describe the aim of the indicator. If you like writing you can of course add more elements, although try not to be redundant, this is really important, skip things such as :
"Yesterday i was dinning with a colleague and he asked me how to get zero-lag filters, since then i tried to..."
This is tiring for the reader and so try not including it.
More Complete Description
A more complete description introduce additional elements regarding your indicator such as your motivation behind its publishing, its calculation...etc.
Such description of the Supertrend indicator could look like this :
Detecting the current market price trend has always been a major challenge in technical analysis, systems relying on the cross between a noisy series and a certain level/indicator can produce whipsaws trades. In order to provide a solution to this problem more advanced indicators have been proposed, one of them being the Supertrend indicator developed by the french trader Olivier Seban.
This indicator aim to detect the current market trend direction, the indicator detect an up-trending market when the price is superior to the Supertrend, and a down trending market when the price is inferior to the Supertrend.
The indicator is an iterative calculation, the core element of its calculation involve creating two bands, denoted as upper/lower, calculated as follows :
upper = hl2 + atr(length)*mult
lower = hl2 - atr(length)*mult
where atr is the average true range of period length and hl2 is the median price defined as : (high + low)/2.
Higher values of length/mult allow the indicator to be less sensitive to shorter price variations, this allow to detect trends of longer period.
Apart from the basic indicator usage described above, the Supertrend indicator can also act as a :
- trailing stop loss, in this case if the closing price cross the value of the indicator, the trade will be closed.
- support/resistance level, in this case an upward movements can be expected after the low price cross the Supertrend, and a downward movement when the high price cross the Supertrend indicator.
In conclusion, the Supertrend indicator is an elegant solution when it comes to detecting the current market price trend, its ability to avoid whipsaws trades makes him a good ally for decision making.
Including Graphics
Graphics of your indicators can add more clarity to your description since visual examples are often easier to understand, the goal here is to see how your indicator interact with the market price. Try including readable graphics, this can mean charts without other indicators (except if your indicator can work in conjunction with other indicators).
However keep your main chart (your current chart layout when publishing the indicator) free of any other indicators/elements, it should only contain the price and your indicator, its the first image people we'll see and if it include other indicators then people will have an hard time telling which one is the one you are publishing.
It can be interesting to show your indicators using different settings rather than the one put by default. You can make use of figures such as arrows or crosses in order to highlight the signals made by your indicator.
Additional Advices
Use a bold text when declaring the title of a section, use italic with text that represent code, formulas, variables names.
You can first write your indicator description on a text editor.
If your code include another work from tradingview don't forget to mention it in the description, for example :
this indicator make use of the "name of the indicator" made by "name of the author" that you can find here "tradingview link of the indicator".
In this case make sure you have the consent of the author of the indicator you are using. This is no option, else you can have your indicator taken down.
Don't include bitcoin wallets/donation links in your indicator description, those go on your signature and nowhere else.
Knowing when not to make a description is important, and by that i mean knowing when not to publish, make sure to read the house rules before you are publishing an indicator.
If you are still struggling then you can try to read other indicators description on the net, if you want a deadly serious description then you can learn from the structure of research papers. For example if your indicator is similar to a moving average try reading descriptions of moving average indicators and inspire yourself from them.
Conclusion
Making a good indicator description is essential, the benefits of doing it are enormous, don't forget that scripts take space in servers. If you are publishing a script and that you know that your description is to short and doesn't explain the aim of your indicator then you are just adding more work for the moderators, its not nice.
Also great descriptions allow you to gain trust and credibility in the community, and more importantly it shows that you care about your indicator, i might be harsh but people that does not care about their indicators does not deserve to publish them (however its not case with you nice reader, right ?).
I hope i can help users with this post, its an important subject, if you have doubts about your indicator description try seeking for help in the pinescript chat, you can even contact me, i will be happy to help.
Thanks for reading, and if you plan to use those advices then thanks for caring, love u :kokoro:
