Readable is a text markup language created in 2018 by LĂ©pine Kong.
| #1721on PLDB | 6Years Old |
git clone https://github.com/lepinekong/readablehumanformatThe ReAdABLE Human Format aims at Agile Documentation by making WRITING and READING document easier for End User and Developer alike, while allowing a high degree of flexibility. Its primary goal is to generate Markdown (and conversion to other formats in the future) while being even simpler (less code to memorize) and richer (adding meta-data is straightforward and creating new semantics is easy).
Red [
Title: "How to Write Good Article"
Build: 1.0.0.4
Credits: ["Sibeesh Venu"]
Owners: ["LĂ©pine Kong"]
References: [
https://www.c-sharpcorner.com/article/how-to-write-good-articles/
]
File: howtowritegoodarticle.red.red
Output-files: [howtowritegoodarticle.red.md]
Categories: [Blogging]
Tags: [Markdown Blogging Writing Documentation Templating Scaffolding]
Dates: [
Creation: 2018-05-12 19:13:42
Update: 2018-05-15 19:09:59
]
Languages: ["english"]
]
Article: [
Title: {How To Write Good Articles}
Source: [
.title: {ReAdABLE Source (version 1.0)}
.text: {[http://readablehumanformat.com/examples/howtowritegoodarticle.red](https://github.com/lepinekong/readablehumanformat/blob/master/examples/howtowritegoodarticle.red)
}
.Published-Url: http://readablehumanformat.com/create.codesnippet.fast
]
Credit: [
.title: {Credit}
.text: {
["How To Write Good Articles" by *Sibeesh Venu*](https://www.c-sharpcorner.com/article/how-to-write-good-articles/)
}
]
Point-1: [
.title: {Point 1: Introduction}
.text: {
Replace this paragraph with your own content, guidance and example are kept available in .guidance and .example fields (metadata) within the ReAdABLE source if you need to remember.
*Guidance:*
>An introduction is very important when you write an article. A good introduction can make the reader want to read further. Trust me, it is very useful too. In this part you can describe what exactly you are going to say/do in the rest of the article. It must be brief. And please never use any code blocks in your introduction, that is never meant to be there. This is the part which lets your readers understand where/what exactly you are intending to do.
*Example:*
>I am neither an expert nor a guru. But still I suppose I have improved by writing articles for the past two years. I still remember my first article, there were so many mistakes. Remember one thing: “Mistakes are the key to success.” Here I will point out a few things which I follow while writing articles. Please feel free to add your own points to this article. I hope you will like this.
}
.image: https://i.imgur.com/rNmBuuv.png
.guidance: {
An introduction is very important when you write an article. A good introduction can make the reader want to read further. Trust me, it is very useful too. In this part you can describe what exactly you are going to say/do in the rest of the article. It must be brief. And please never use any code blocks in your introduction, that is never meant to be there. This is the part which lets your readers understand where/what exactly you are intending to do.
}
.example: {
I am neither an expert nor a guru. But still I suppose I have improved by writing articles for the past two years. I still remember my first article, there were so many mistakes. Remember one thing: “Mistakes are the key to success.” Here I will point out a few things which I follow while writing articles. Please feel free to add your own points to this article. I hope you will like this.
}
]
Point-2: [
.title: {Point 2: Background}
.text: {
In this part, you can explain what made you write this article. You can explain the problems you faced here, or when you had this problem. This should be brief too, here you can also include source code. Please do remember that this is just the background, so it is not advisable to include full source code and explain it here.
}
.guidance: {
In this part, you can explain what made you write this article. You can explain the problems you faced here, or when you had this problem. This should be brief too, here you can also include source code. Please do remember that this is just the background, so it is not advisable to include full source code and explain it here.
}
.example: {
Example: Last week one of my friends asked this question: "How do you write good articles?" I am dedicating this article to him. I hope he will like this.
}
]
Point-3: [
.title: {Point 3: What are you going to do?}
.text: {
Here you can explain the things which you are going to do in this article. You can list them for better readability. You can explain these points one by one. You can also add some code snippets. But whenever you add any code, please try to explain even if it is basic. That will help some beginners to understand things more easily. You may feel that this basic explanation is not necessary as you have so much experience and you may be good at it. But what about the beginners? I always believe they are the real beneficiaries of your articles. We must concentrate on both kinds of users; i.e., beginners and experienced.
}
.image: https://csharpcorner-mindcrackerinc.netdna-ssl.com/article/how-to-write-good-articles/Images/What-you-are-going-to-do.jpg
.guidance: {
Here you can explain the things which you are going to do in this article. You can list them for better readability. You can explain these points one by one. You can also add some code snippets. But whenever you add any code, please try to explain even if it is basic. That will help some beginners to understand things more easily. You may feel that this basic explanation is not necessary as you have so much experience and you may be good at it. But what about the beginners? I always believe they are the real beneficiaries of your articles. We must concentrate on both kinds of users; i.e., beginners and experienced.
}
]
Point-4: [
.title: {Point 4: How are you going to do it?}
.text: {
This can be the continuation of point three. This is where you can explain the possible ways that you can fix your problem, or the possible ways to achieve the same tasks. Any tasks can be achieved in different ways right? So when you write any article, you must think from all perspectives.
This will make your article rich in content. And this is where you must concentrate more on the coding part. When you write code in your article, it must be formatted well. If you use WordPress as a CMS (Content Management System) for your blog, you can go for any syntax highlighter plugins, or you can customize your own. If you post the article in any of the social communities, please use their formatting options.
If you have any images which explain the workflow for any tasks, it is always advisable to include those. An image is more understandable than reading the content, but always limit yourself to not include more than 10 images per article. When you include the images, please try to convert them to a particular size (example: width: 650 PX), this will make your article look good. But no worries if you have a low resolution image, and if you think enlarging that will cause any clarity issues, you can always use the same without conversion.
One thing you must remember is that you can always include all the things you have tried and what the output was that you got from it. If you do so, your reader will see that if he or she does that, they will get the same output. So it is not only about the the scenario which works fine, but also about the errors/problems.
}
.guidance: {
This can be the continuation of point three. This is where you can explain the possible ways that you can fix your problem, or the possible ways to achieve the same tasks. Any tasks can be achieved in different ways right? So when you write any article, you must think from all perspectives.
This will make your article rich in content. And this is where you must concentrate more on the coding part. When you write code in your article, it must be formatted well. If you use WordPress as a CMS (Content Management System) for your blog, you can go for any syntax highlighter plugins, or you can customize your own. If you post the article in any of the social communities, please use their formatting options.
If you have any images which explain the workflow for any tasks, it is always advisable to include those. An image is more understandable than reading the content, but always limit yourself to not include more than 10 images per article. When you include the images, please try to convert them to a particular size (example: width: 650 PX), this will make your article look good. But no worries if you have a low resolution image, and if you think enlarging that will cause any clarity issues, you can always use the same without conversion.
One thing you must remember is that you can always include all the things you have tried and what the output was that you got from it. If you do so, your reader will see that if he or she does that, they will get the same output. So it is not only about the the scenario which works fine, but also about the errors/problems.
}
]
Point-5: [
.title: {Point 5: Always include output}
.text: {
An output is the outcome of what we tried, right? So what if you don't include that? Isn’t that bad? You can include the output as an image or any content. It can be any result set too.
}
.guidance: {
An output is the outcome of what we tried, right? So what if you don't include that? Isn’t that bad? You can include the output as an image or any content. It can be any result set too.
}
]
Point-6: [
.title: {Point 6: Include source code as a downloadable format}
.text: {
Please add source code as a downloadable format whenever possible. This will definitely help your reader, so that he/she doesn’t need to worry about the initial set up. We all are a community, guys, and we love helping each other. Am I right?
}
.guidance: {
Please add source code as a downloadable format whenever possible. This will definitely help your reader, so that he/she doesn’t need to worry about the initial set up. We all are a community, guys, and we love helping each other. Am I right?
}
]
Point-7: [
.title: {Point 7: Format the entire content}
.text: {
There are so many things you must concentrate on when it comes to formatting. I am listing a few of them here.
- Use the same font for the entire article
- Use bold for the headings
- Highlight the lines, if it is very important (Example: Notes)
- Use code formatter when you write codes
- Resize and align images properly
- Make sure that that headings start with a capital letter (CamelCasing)
}
.guidance: {
There are so many things you must concentrate on when it comes to formatting. I am listing a few of them here.
- Use the same font for the entire article
- Use bold for the headings
- Highlight the lines, if it is very important (Example: Notes)
- Use code formatter when you write codes
- Resize and align images properly
- Make sure that that headings start with a capital letter (CamelCasing)
}
]
Point-8: [
.title: {Point 8: Give credit}
.text: {
This is very important. Whenever you take something from any site, please try to give credit to the content owner by providing the links/name. For example, if you are taking an image from any site, you can include the site name just below the image. Trust me, this will make you genuine. And in the end, it is all about being genuine right?
}
.guidance: {
This is very important. Whenever you take something from any site, please try to give credit to the content owner by providing the links/name. For example, if you are taking an image from any site, you can include the site name just below the image. Trust me, this will make you genuine. And in the end, it is all about being genuine right?
}
]
Point-9: [
.title: {Point 9: Write a conclusion}
.text: {
The conclusion is the last part of your article; you can summarize the things you have written here. And also if you want, you can always ask some questions to your readers so that the bond between you and your readers will be in multibind format (Yes, like we have in Angular JS. LOL). You can always ask for feedback; feedback is something that we all are looking for. Each and every piece of feedback is valuable whether it is negative or positive. If you get any negative feedback, be happy and try to improve on the things that are being suggested.
In a speech in South Africa in 1890 Mahatma Gandhi said this:
* * “A customer is the most important visitor on our premises. He is not dependent on us. We are dependent on him. He is not an interruption of our work. He is the purpose of it. He is not an outsider of our business. He is part of it. We are not doing him a favour by serving him. He is doing us a favour by giving us the opportunity to do so.”
}
.guidance: {
The conclusion is the last part of your article; you can summarize the things you have written here. And also if you want, you can always ask some questions to your readers so that the bond between you and your readers will be in multibind format (Yes, like we have in Angular JS. LOL). You can always ask for feedback; feedback is something that we all are looking for. Each and every piece of feedback is valuable whether it is negative or positive. If you get any negative feedback, be happy and try to improve on the things that are being suggested.
In a speech in South Africa in 1890 Mahatma Gandhi said this:
* * “A customer is the most important visitor on our premises. He is not dependent on us. We are dependent on him. He is not an interruption of our work. He is the purpose of it. He is not an outsider of our business. He is part of it. We are not doing him a favour by serving him. He is doing us a favour by giving us the opportunity to do so.”
}
]
]
unless exists? lib: %lib/ReAdABLE.Human.Format.lib.red [
lib: http://readablehumanformat.com/lib.red
]
do read lib
do read .to-file "C:\rebol\.system.user\.code\.domains\.apps\Authoring\libraries\.system.user.apps.authoring.library.red"
markdown-gen
; deploy to .github local workspace
try [
.copy-file %howtowritegoodarticle.red
.copy-file %howtowritegoodarticle.md
]