Author Guidelines

Overview
All authors, editors and publishers are encouraged to read these guidelines. By following these guidelines, you will make the collaboration process smooth and enjoyable for all. If you don't agree with any of them, do make suggestions. It's likely that these guidelines will evolve as more members start using Devopedia.
Many of these guidelines are inspired by and adapted from Wikipedia Policies and Guidelines. Our licensing is compatible with that of Wikimedia Foundation. At Devopedia, we don't impose strict policies. Our guidelines are best practices that make common sense. The community defines them and is free to change them if found unsuitable. Changes to these guidelines are via forum discussions, mediation, voting, or a combination of these.
Two other web pages give a good introduction to Devopedia, About Devopedia and Terms of Use. These two pages contain information relevant to authoring of content on Devopedia. Some of that information are probably not repeated in these guidelines. Hence you are encouraged to read those pages as well.
If you're a first-time author on Devopedia, you can study some existing articles to get an idea of what we cover, the style of writing and the format. Browse recent articles.
Articles are written in Markdown syntax, which is briefly described in the Syntax & Style page.
If you like to learn from examples, head to the Good & Bad Examples page.
Authors and reviewers can download a cheatsheet of reference and citation syntax.
How-To Guides

View all the how-to guides at a playlist on our YouTube channel. We feature a couple of them below:

Introduction to Devopedia, for New Authors

How to Create Vector Illustrations with Draw.io

External Resources

Here are some external resources to help you improve your technical writing skills:
User Roles

Figure 1: User Roles on Devopedia

Visitor
Visitor is someone who accesses the content without logging into the site. Visitors may be permitted to anonymously like or share content.
Author
Author refers to anyone who creates and edits content.
Editor
Editor is an author who is also authorized to edit content created by others. By default, all authors are promoted to the status of editors.
Publisher
Publisher is someone authorized to publish a new article. Authors and editors can create new articles but they will not be visible to visitors until published by publishers. Only publishers have the privilege to unpublish an article. Edits to already published articles appear online immedidately. In this case, publishers have no special role. Publishers are nominated by members based on their contribution and respect within the community.
Contributor
Contributor is a term collectively applied to authors, editors and publishers. Collaborator is an alternative term.
Reviewer
Reviewer is a contributor who participates in discussions on articles. Reviewers give suggestions or point out errors so that editors can improve articles. Moderator is an alternative term.
User
User is a term collectively applied to anyone who uses Devopedia. This includes contributors and visitors.
Member
Member is a term almost synonymous with user. Since Devopedia is a community of developers, this term is often used to acknowledge a sense of belonging to the community.
Developer
Developer is anyone who engages in aspects of engineering that deal with product or service development. This includes architecture, design, coding, testing, deployment, integration, etc.
Article Lifecycle
Figure 2: Lifecycle of an article on Devopedia

An article can be in one of five states as depicted in Figure 2:
1. New
  When a new article is created, it enters this state. The article is not stored on the server until it is submitted. Hence a new article remains within the context of the browser of the author creating it. It's contents are lost if not submitted to the server.
2. Unpublished
  Once a new article is submitted it enters this state. It remains in this state until someone with publishing privileges changes its state. Unpublished articles are visible only to users logged into the site.
3. Locked
  When an existing article, published or unpublished, is to be edited, it enters this state. In this state, only the user currently editing the article has permissions to edit it. Locked state can also be entered automatically if the backend algorithms detect suspicious edits on an article and decide to prevent further edits until someone reviews the article. Locked articles will be visible to all users.
4. Published
  This state indicates that the article is visible to all users of the site. Note that an article cannot directly move from Unpublished to Published state. All changes must transition via the Locked state.
5. Archived
  If the article is deemed to be inappropriate for the nature of Devopedia platform, it is archived by publishers. An archived article will no longer will visible to anyone.
All authors can open an article for editing and thereby lock it. When an author saves an article, it will return to its previous state of Unpublished or Published. Only publishers have permissions to change an article state among Unpublished, Published or Archived. An article once published will remain published. Publishers may choose to unpublish an article only in exceptional circumstances. Note that this action will break links pointing to the unpublished article.
With reference to Figure 2, here's a typical lifecycle of an article:
1. When a new article is created, it's often in an incomplete state. The author therefore decides to save it as a draft. When draft is submitted from a web browser, it is saved for the first time on the server. Since this is a draft, the article is visible only for its author. Author continues to edit the draft. The state of the article remains New so long as only it's drafts are saved.
2. The author decides to save the article and make it visible to other contributors and reviewers. The new article is submitted from a web browser. It is saved. It thus moves from New to Unpublished state.
3. Anyone with privileges wishing to edit the article, may move the article from Unpublished to Locked state. No one but the current editor may edit the article in Locked state. This transition may also be triggered by backend algorithms to prevent edits.
4. An Unpublished article when saved after an edit, will re-enter Unpublished state. An Unpublished article that's been in Locked state for too long for editing, will timeout and automatically re-enter Unpublished state.
5. A publisher will give his/her approval to an article by moving it to Published state. A Published article that's been in Locked state for too long for editing, will timeout and automatically re-enter Published state. A Published article when saved after an edit, will re-enter Published state.
6. Anyone with privileges wishing to edit the article, may move the article from Published to Locked state. No one but the current editor may edit the article in Locked state. This transition may also be triggered by backend algorithms to prevent edits.
7. When an article is in Locked state, the current editor can also save changes as a draft. It's possible for an article to have multiple drafts but each author can have only one draft of the article. When an article's draft is saved, the article will remained in Locked state so that the current editor can continuing editing it.
8. In rare cases, an article created by mistake or deemed as inappropriate, will be archived by a publisher.
As noted above, any author can edit and save an article, thereby creating a new version of that article. However, the system does a check for a "suspicious" edit. If the edit is deemed suspicious, then it's flagged for a review. No new article version is created in this case. Changes are saved as a user draft but now this draft becomes visible to publishers for review purpose. Author may continue editing the draft until a publisher gets a chance to review the article. Review can't happen if the article is locked, which happens if the author continues to edit the draft. A publisher can approve or reject the edit, and give suitable review comments to support the decision.
To prevent multiple edits of an article at the same time, and hence avoid write conflicts, only one edit is allowed at a time. This is the reason an article becomes Locked when someone is editing it. The person doing the edit may forget to save the article, close the browser, click browser's back button or be inactive for a long period. This will indefinitely prevent others from editing the article. To recover from such a scenario, a timeout is implemented. Once the timeout expires, the article will move to its previous state (Published or Unpublished) so that others can edit it. On a Locked article, everyone will be able to see who is currently editing it and when the timeout expires.
Content Guidelines
Articles must be relevant to the work of a developer. We take a broad definition of a developer. He/she may be involved in architecture, design, coding, integration, testing, debugging, tooling, requirement analysis, use case analysis, deployment, documentation, and more. A developer may be working on hardware or software of any platform, OS, equipment or device. A developer may be working in any domain or application from aerospace to renewable energies, from semiconductor technology to frontend web development.
While articles on obsolete technologies are welcome, prefer to contribute towards new technologies. Often new technologies are the ones for which there's a lack of quality resources on the web.
Before creating a new article, search within Devopedia if it already exist. Sometimes the article may exist under a different title that's synonymous with what you have in mind.
For someone new to a topic, article should address the sort of questions beginners are likely to have.

Figure 3: Core content guidelines adopted from Wikipedia

Neutral Point of View
Articles must express an unbiased viewpoint. Don't take sides with specific technologies just because you are familiar with them. For example, don't claim that Google Chrome is a better browser than Microsoft Edge. Instead, you may refer to browser popularity and limitations. You may make inferences from these facts or let readers form their own inferences.
Verifiability
Provide citations and links to web resources that are relevant to articles. This helps editors and publishers to verify content. This brings greater credibility to articles. They also provide readers a path for further reading. Naturally, citations are only as good as the reputation of the sources from where information is cited. Choose sources that are reputable and unbiased. Peer-reviewed journals, mainstream newspapers, books and magazines from noteworthy publishers, and approved textbooks are some examples of good sources. Avoid sources that are self-published, unknown, biased or opinionated.
No Original Research
Devopedia is not the place to publish original research. You may refer to externally published sources that show original research and results.

You may write articles that compare one technology with another. Such articles should adhere to a neutral point of view. You may cite articles of research that compare technologies but you should not make an opinionated statement of your own. This also means that you can't directly recommend one technology over another.
Avoid words or expressions that may suggest bias. Here's a sample: great, outstanding, innovative, awesome, it is often reported, it is widely claimed, experts claim, supposed, alleged, unfortunately, interestingly.
Avoid ambiguous relative time references such as lately, recently, currently, to date, in the past. Instead be more specific by using absolute time references such as mid-twentieth century, 1975, 4th September, at the age of eight.
Avoid expressions that give imprecise information. Here's a sample: sometimes, often, once in a while, in some teams, in many systems. For example, if a published source states that "only 10% of developers use vim as an editor", don't say that "vim is rarely used".
Since anyone can edit articles on Devopedia, and since each one may come with his/her own opinion, focus on facts rather than give your own opinions. Convey these facts in a neutral language since it's possible to distort facts using opinionated sentence construction. Likewise, don't try to pass off your opinions as facts. These guidelines help to avoid conflict.
To preserve neutrality, consider all points of view. Don't cite sources that reinforce your beliefs and conveniently leave out alternative viewpoints.
Rephrase content. Never plagiarize content. You may explicitly quote content from other sources but cite the source. It's okay to quote a few sentences but don't lift entire paragraphs.
It's okay to copy code with source attribution provided it's compatible with Devopedia's licensing.
Content should not be copy-paste from a single source. Rephrase in your own words or summarize content from multiple complementary sources.

Media

You are permitted to create your own media and make them available to the Devopedia community under our terms of licensing. Media that you create are not considered original research provided you don't use them to convey original or previously unpublished ideas. Prefer open formats that can be edited by others using commonly available tools.
When using third-party media (audio, video, image, etc.) use only those compatible with Devopedia's licensing mechanism. Be sure to give attribution to the source. Give attribution even if the content is in public domain or does not require attribution. This helps readers in verifying the content.
You are permitted to directly link to media available at external web sites. Do include source attribution. At least for images, it's preferrable to upload them to Devopedia.org and then link to them within the article. When doing so, include attribution to the source.
When linking to external video, the following sites are supported: YouTube, DailyMotion, Vimeo. Videos from other sources may also work. Don't link to URLs streaming live video.
Give every media a suitable caption. Caption should be in normal case without unnecessary capitalization. For example, say "Comparing the performance of arrays and linked lists" rather than "Comparing the Performance of Arrays and Linked Lists".
For all uploaded media, limit the size to 250 KB (image), 2.5 MB (audio) and 25 MB (video).

Naming Articles

Article titles can be descriptive but only if you can't find a suitable name. For example, an article titled "A Tool for Browsing the Web" can be simply titled "Web Browser".
An article titled "Less" is ambiguous. It could mean UNIX's less command, the Less language that's related to style sheets or Large-Scale Scrum. In such a case, the main page would be a disambiguation page with links pointing to the other pages. Each of those other pages would be named thus: Less (UNIX), Less (Style Sheet Language), Large-Scale Scrum. This implies that sometimes you may have to rename existing pages to make room for alternatives or disambiguation pages.

Article Sections

Organize content into a narrative flow. An article must have the following parts:
- Summary
  This is limited to a maximum of 150 words. This gives a summary of the topic. It could be an overview or a definition. One still image is allowed in this section. You can include an unnumbered list within the summary.
- Discussion
  Rather than have a multi-paragraph description, we choose a Q&A format because information is organized into small chunks of text and hence easier to read and follow. Authors can decide on the questions. Any number of questions can be included. Each pair of question and answer must be limited to a maximum of 200 words. The discussion section in total must not exceed 2000 words. Whereas summary is the gist, this section explains the topic is greater detail. To help readers understand, it's often useful to present a historical context. For example, why was C++ invented and what limitations in C did it attempt to overcome? Why did C++ make sense from the late 1980s and early 1990s? Answering such questions will help readers appreciate the topic and understand it better. Media (audio, video, image, etc.) are allowed in this section and limited to a maximum of 1 item per answer. You can include an unnumbered list within an answer.
- Milestones
  This section gives historical information relevant to the topic being discussed. Some of these milestones might include when a particular technology was invented and by who; when was the language standardized; when a particular version was deprecated; when a framework eclipsed another one. These details have to be entered in a specific format so that it can be displayed as a visually appealing timeline. Still images are allowed in this section and limited to one per milestone. We impose a limit of 15 milestones with a maximum of 100 words to describe each one. This implies that sometimes it may be necessary to pick the most important milestones. Don't use lists within milestone descriptions.
- Sample Code
  Some articles might benefit from sample code that illustrates better the topic under discussion. While inline code (usually one-liners) is allowed in other sections, this is the only place for multiline code blocks. Use code comments as a means of explaining the code. The purpose of this code is to enable explanation by example. Hence, use only code snippets. Use minimum amount of code that illustrates the concept. Don't aim to show complete working code. Devopedia is not the place for sharing working code. Devopedia will apply syntax highlighting on the code automatically using third-party plugins such as GeSHi-Generic Syntax Highlighter. Sample code can be shown in up to 6 different programming languages. Formatted code must be limited to a maximum of 500 lines per language with a 80-character limit per line.
- References
  This is the list of references that have been directly cited in the article. There is no limit to the number of references that can be listed.
- Tags
  This includes a list of primary and secondary tags associated with the article.
- See Also
  This is a list of articles found elsewhere on Devopedia. All articles in this list are related to the current article. This serves as a good signpost for readers to navigate to related topics. A maximum of 6 articles can be listed. It doesn't matter if these topics are missing their own articles on Devopedia. Our goal as authors would be to address these gaps. This too helps in breaking up a long article into smaller articles, each of which can be written at its own pace.
- Further Reading
  This is a list of web links to resources external to Devopedia. Since each article is limited to essentials, these links are important for users who wish to learn the topic in greater depth. These links are not necessarily referenced or cited in the content. A maximum of 6 links can be listed.
Devopedia backend system will generate the following additional sections automatically:
- Authors
  To recognize the contributions of authors, the article includes a list of its authors. Authors are ranked by the number of DevCoins they have earned for the article.
- Article Stats
  This might include word count, number of authors and number of edits. Word count is taken from Summary, Discussion and Milestones sections. Words in other sections are not counted. Lines of code from the Sample Code section will be counted separately.
- Cite As
  Anyone wishing to cite the current article, can copy this text.
- Recent News
  Devopedia will source and display a short list of news articles relevant to the current article. Sometimes authors might realize that a news is directly relevant to the article. They could then use it to update the summary, description or milestones. This is currently not implemented.
- Resources
  Devopedia will source and display or embed relevant images, audio and video clips. Devopedia will take care to properly attribute these to the correct sources. This is currently not implemented.
Word Count

There's a strict limit on the number of words for some sections of the article. We like articles that are concise and not verbose.
We impose these limits because we want authors to write in a concise manner. We want readers to understand the concept quickly without feeling intimidated by lots of text. An upper limit on word count also encourages authors to think in terms of smaller building blocks of knowledge. Such blocks can be interlinked later by Devopedia's tools to form learning paths.
Word count includes all words visible on the web browser, including captions to media. This means that HTML tags and inline citations are not counted.
The following are some of the current limits on word count (full details are in Figure 4):
- Summary: Maximum 150 words.
- Discussion: Maximum 200 words per Q&A. Discussion as a whole has a maximum of 2000 words. There's no limit on the number of questions.
- Milestones: Maximum 100 words per milestone. Maximum 15 milestones. Milestones as a whole has a maximum of 1200 words.
- Sample Code: Rather than word limit, there's a limit on number of lines of sample code. We allow a maximum of 500 lines per code sample with maximum 120 characters per line. Maximum 6 code samples.
Figure 4: Limits for an article without warnings.

Arrange content into named sections as noted earlier. Don't introduce extra sections.
You can link to external sites in sections Summary, Discussion, Milestones and References. Auto-generated sections may contain external links.
For internal links within Devopedia, authors don't need to explicitly code the links in HTML from one article to another. Devopedia will take of the linking automatically. This is also important for one reason: if an author changes an article's title, its URL will also change. Hence, we take the approach of generating internal crosslinking on the fly. In addition, Devopedia will implement URL redirection for external referrers who are using older URLs. In any case, if you wish to explicitly include an internal link, you are allowed to do so.
Personal or company biographical pages are not permitted. For example, Devopedia is not the place for pages on "Steve Jobs" or "Apple". However, pages that relate to industry alliances, associations, consortiums, standards bodies or community organizations are allowed. For example, a page on "Internet Engineering Task Force" is allowed. Pages that describe commercial products are allowed, such as, "Windows 10" or "Apple Macintosh".
Tagging Content
You must associate one or more primary tags with every article. Optionally, you can associate secondary tags as well. An article can have a maximum of 8 tags.
Currently the following primary tags are defined:
- Web
  Articles that relate to web architecture, web components, web services or web applications will appear here. Some examples include pages on HTTP, Websockets, client-server model, cross-site scripting, cookie, and more. Web frameworks such as Rails, Django, Laravel can also appear here. Web stacks such as LAMP or MEAN can appear here.
- Mobile
  Articles related to mobile development will be tagged here. Example include Android, React Native, MIT App Inventor, app store, and more.
- Embedded
  Examples of articles here are RTOS, MCU, ASIC, serial interface, endianness, Harvard architecture, firmware, soft real time, and more.
- Design
  Design can refer to visual design such as for a web page or software design such as for modules and their interfaces. Both are covered here. Examples include design patterns, decorator, storyboard, user experience, and more.
- Languages
  The focus here would be on programming languages. Each popular langugage will have its own article page. Pages related to programming paradigms such as OOP or functional programming will appear with this tag. General concepts of programming can also be here.
- Tools
  This includes IDEs, SDKs, code editors, compilers, debuggers and more. Specific tools such as Sublime and Eclipse can have their own individual article pages. Some tools affect the installation. Examples of these are package managers and dependency managers. Tools need not just software. They can include community platforms such as Mozilla Developer Network or StackOverflow.
- Data
  This is about data sources, data formats, encodings, types and methods of storage. It is also about the many aspects of data processing including cleaning, formatting, visualizing and analyzing. Databases are also covered here.
- Algorithms
  The typical articles here would include sorting, searching and scheduling algorithms. Algorithms span a variety of domain verticals. Hence it will be common to apply suitable secondary tags to indicate the domain of application. For example, an article on Naive Bayesian classification would come here but it would also be tagged as "Machine Learning". Likewise, Huffman coding would come here but it would also be tagged as "Information Theory", "Lossless Compression" and "Source Coding".
- Networking
  Networking protocols will feature prominently here. This could include TCP/IP, DHCP, ARP, and more. Concepts of wired and wireless networking will be covered. Definitions of networking devices are covered here.
- Security
  This includes algorithms such as RSA, SHA1, MD5, and more. Principles of security would be covered. Terms used in relation to security would be covered. Some examples are malware, ransomware, trojans, packet sniffing, signal jamming, and more.
- Testing
  Different types of testing will have their article pages. Examples include unit testing, regression testing, performance testing, and more. Methodologies of testing and development would include Agile testing and Test-driven Development.
- System
  System aspects usually not considered by a traditional developer would come here. This might be related to server deployment or configuration. DevOps and Continuous Integration would come here. Cloud computing would also feature under this tag. The process of developing and managing a project would come here. This might include articles on Scrum and Agile.
You cannot create additional primary tags. You cannot modify or delete existing primary tags. You may however initiate discussions for the same.
You can create and associate any number of secondary tags to articles. Devopedia will prompt the author with existing tags. Try to choose one that's closest to what you have in mind. If none of the existing tags are suitable, you are allowed to create your own tag.
There's no hierarchy among secondary tags, although topically there may be a hierarchy. For example, we can say that Web frameworks, CMS and WordPress have a hierarchy. But as authors you don't need to specify this hierarchy. You can simply use all three secondary tags on an article related to WordPress.
These tags will be used to create learning paths. Such paths will be created in a semi-automated manner where it will be initially auto-generated and subsequently edited by publishers. This gives users a structured approach to learning a particular technology.
Syntax & Style
Write in plain English as far as possible. This means avoid using technical jargon except when it relates directly to the article. It also means using simpler words. Here are some words that can be replaced with simpler words: abundance (plenty), commence (start), elucidate (explain), peruse (read), relocate (move), etc. For more information visit the pages How to write in plain English and List of plain English words and phrases.
Use short sentences of 15-20 words. They're easier to understand. Sentences should be clear and concise. For example, "Furthermore, large volumes of water are also required for the process of extraction" can be simplified as "Extraction also requires large volumes of water".
Prefer active verbs rather than passive verbs. For example, say "throw an exception" rather than "exception must be thrown".
Avoid nominalisation, which are nouns formed from verbs. For example, "failure" is a nominalisation of "fail". We could say "The new deployment resulted in a failure" but it's better to say "The new deployment failed". Here are more examples with their simpler alternatives: made arrangements for (arranged), took the decision (decided), performed the development of (developed), etc.
Place most important information first and in the main clause. For example, "The customer was happy despite many minor software bugs" highlights the happy customer. "The software had many minor bugs, though the customer was happy" highlights buggy software.
Don't try to be formal in your writing. Instead imagine you're talking to the reader. Prefer contractions. For example, say "don't" rather than "do not".
For article titles, make the first letter of each word uppercase. For example, say "Web Browser" rather than "Web browser". Titles are usually nouns or noun phrases. However, don't uppercase prepositions and conjunctions. For example, say "JavaScript to TypeScript Migration" rather than "JavaScript To TypeScript Migration".
In some contexts, pronouns can introduce ambiguity. Use nouns instead. In this example it's not clear which language the person likes, "C++ is a popular language, and so is Java. I like the language". Instead say, "C++ is a popular language, and so is Java. I like Java".
Avoid using "there is" or "there are" since they're often not necessary. For example, "There is support for multiple threads in Java" can be rewritten as "Java supports multiple threads".
Avoid idioms since they can be hard to understand for international readers. Morever, idioms may not suit the technical nature of the content published on Devopedia.
Minimize adjectives and adverbs. They also tend to lead authors towards opinionated views. Instead, stick to facts. For example, instead of saying "Visualization updates are blazingly fast", say "Visualization updates are faster by 50%".
Use parallel structures for phrases and clauses to make reading easier. For example, "For performance, we recommend C language and using more RAM" has a mixed structure since "C language" is a noun and "using" is a verb. Instead say "For performance, we recommend C language and more RAM" or "For performance, we recommend using C language and installing more RAM".
Use lists where you wish to describe a number of items. Lists are easier to read. They organize content better. If each list item is just a word or a phrase, then such a list may be compressed into a sentence. If each list item includes a description, then list is a good idea. All items of the list must follow similar styling.
For emphasis, use italics or bold text. Do not use uppercase for emphasis. Also, use emphasis only when really required. Don't overuse it. Use italics when you define or introduce a new term but often such a term may have its own article page on Devopedia. In such a case, use a link rather than italics. Use boldface when you to call the reader's attention to something important.
Where there are alternative styles, be consistent and use only one within an article. On an existing article, understand the currently used styles before editing it.
For dates, one of these formats could be used: "4 June 2010"; "June 4, 2010"; "2010-06-04". Contractions are allowed so that "June" could be written as "Jun" or "JUN".
For specifying dates in milestones, example formats are "500 BC", "755 AD", "1000 AD", "Aug 2003" and "2003". Note that year can have only four digits and month must be written as three-character abbreviation. When AD or BC suffix is used, month should not be included. Following date examples are not allowed: "12000 BC", "Jun 2010 AD", "June 2010".
For time references, you may use for example "10 PM" or "10 pm".
Use "US" and "UK" rather than "U.S." and "U.K."
Mention abbreviations after their expansions. Abbreviations must be within parentheses. For example, "Artificial Neural Network (ANN)" or "Artificial Neural Networks (ANNs)". These are indexed by Devopedia and used to expand abbreviations where expanded forms are not provided.
Separate units from the value. For example, say "5 kg" rather than "5kg".
You may use either US English or British English but don't mix the two in the same article.
When linking to articles within Devopedia or web pages external to Devopedia, the displayed text should be descriptive and not the link itself. For example, say [Download Firefox](https://www.mozilla.org/en-US/firefox/) rather than [https://www.mozilla.org/en-US/firefox/](https://www.mozilla.org/en-US/firefox/) .

Markdown & HTML

All edits can be done within an editor that supports Markdown, which makes it easier for authors. Devopedia will transform these into HTML on the fly when an article page is rendered.
Use of HTML tags is not allowed. This also means that any JavaScript and styling code that you include within content will be ignored, except when they're included as code examples. Devopedia will also remove all HTML tags and tag attributes.
When entering content, anything that does not correspond to the article's standard structure will be stripped out by Devopedia.
When you're editing an article, you can refer to full details of the Markdown syntax. Briefly, the main ones are:
- **...*** for bold
- __...__ for italics
- [text](url) for hyperlink
- *... for a list item
- *... for a list within a list
You may use tables but only in the Discussion section. Note that tables are not exactly friendly to responsive design. Where possible, Devopedia may attempt to transform tables into other syntax to improve user experience. Tables must be formatted in Markdown as follows. Each row should start and end with | character. Cells are separated with | character. Any such character within the table must be escaped as \|. Finally, you can specify the alignment: :- for left, :-: for center and -: for right. First row is the table header. Second row specifies the alignment.
```
| Left-aligned | Center-aligned | Right-aligned |
| :---         |     :---:      |          ---: |
| git status   | git status     | git status    |
| git diff     | git diff       | git diff      |
```
Start a line with >> to style short memorable text quoted from external sources. This will be rendered bigger to make it stand out. Ensure the quote on a paragraph by itself. Cite the source when using such quotes. Blockquote is allowed only within sections Summary, Discussion and Milestones.
When creating hyperlinks, sometimes the linked text and/or URL may contain [] or () characters. Devopedia fails to handle these properly. In such cases, use ] for ], and ) for ).
Any content that has literal HTML tags that need to be displayed without interpreting the HTML will cause problems. In such content, use < for <.
Mathematical equations can be included in content. MathJax is used for this purpose. The default math delimiters are $$...$$ and \[...\] for block display of equations, and $...$ for inline display. Please consult MathJax v2.7 documentation for full details. Devopedia currently uses MathJax v2.7.1.
Avoid styling equations in terms of size, colour, border, background, and so on. We prefer that all equations are rendered uniformly with the default styles.

References & Citations

Figure 5: Reference syntax with some examples.

For references and citations, use the Chicago Manual of Style (Author-Date system). While there are many alternatives, the Chicago Manual of Style is as good as any. Since this style has two variants, use the author-date system. Study the examples by following the preceding link.
Authors and reviewers can download a cheatsheet of reference and citation syntax.

Devopedia has adapted the Chicago Manual of Style in a minor way. Figure 5 shows the reference syntax along with some examples. Each reference that's accessible online is linked to a URL. Only some fields are mandatory but authors are encouraged to fill as many details as possible. We describe possible values for the fields noted in Figure 5:
- Author Name
  Mention names of all authors. The formatting varies depending on the number of authors (assume 2000 as the year of publication in the following examples):
  - Single author: lastName, firstName. Eg. Smith, John and cite as [(Smith 2000)]
  - Two authors: lastName, firstName, and firstName lastName. Eg. Smith, John, and Julie Walters and cite as [(Smith and Walters 2000)]
  - Three or more authors: we show a three-author example: lastName, firstName, firstName lastName, and firstName lastName. Eg. Smith, John, Julie Walters, and Ruby Kent and cite as [(Smith et al. 2000)]
  First names can be shortened to just the initials. This is permitted. Where there's a middle name, treat it as part of the first name field described above. For example, the name "John Jacob Smith" will be written as "Smith, John Jacob". Some exceptions are possible. For example, "Rob van Ommering" can be written as "van Ommering, Rob" where "van" is joined with the last name field.
  Where authors are editors or translators, mention these as well. Eg. Smith, John, and Julie Walters (eds) or Smith, John (trans)
  If the author's name is unknown, use the website or company name. Some sources may have a prominent sub-domain, such as https://docs.microsoft.com/. In this case, both Microsoft and Microsoft Docs are acceptable.
  If source is collaborative and edited by many authors (such as in Wikipedia, Mozilla Developer Network, documentation at Microsoft), use the website or company name.
  Sometimes it's possible to go up the URL path to find out the author's name. This is common for lecture notes or slides hosted on college websites. By going up the URL path, we can find out the name of the lecturer/professor and full details of the course.
- Year of Publication
  This is usually visible on the online page. If not, the page source may contain the date of publication. Search for either "published", "modified" or "date" strings in the page source.
  If date of publication can't be determined, use the current year by default.
  Where the source is collaborative and constantly edited, use the last update date. This is because the source would have been incomplete at the date of creation. Quoting the update date makes more sense.
  Citation uses author name field and year of publication field. If these result in the same citation format for multiple references, then use an alphabet suffix. Eg. Smith, John. 2000a. and Smith, John. 2000b. should be cited respectively as [(Smith 2000a)] and [(Smith 2000b)]
- Title of Article or Paper
  Mention the title within double quotes.
  A title might end with a question mark or exclamation mark. If not, end the title with a period. In all cases, punctuation must be inside the quotes.
  Sometimes a title may be displayed in uppercase on the webpage. Convert this into normal or title case while formatting the reference.
  Where source is a deck of slides, use the title either from the deck or from the site where the slides are published (such as SlideShare or YouTube). Use your discretion to select the title that more accurately represents the content.
- Details of Publication
  Online publishers publish a variety of content. Mention if it's a blog, presentation slides, tutorial, documentation, press release, etc.
  For a technical journal publication (such as from IEEE, ACM, etc.) mention full details including volume, issue/number, page number, and month of publication. If it's conference proceedings, include location and dates of conference.
- Website or Publisher's Name
  Mention the full name, not the website's domain name. Eg. say MIT Technology Review rather than technologyreview.com
  There are sites that aggregate content. Particularly for technical journal publications, CiteSeerX, ResearchGate, Semantic Scholar, etc. are examples of aggregators. In these cases, find out and mention the name of the original publisher. Don't use the name of the aggregator.
- Date of Publication
  This is similar to the Year of Publication except that we focus here on month and day fields. Eg. July 25 or August 7-12
  If this is not available or unknown, omit this field.
- DOI
  This is applicable only for technical journal publications. It's common to omit this field if the URL field already points to the original source.
  In case the URL field is not the original source, it's essential to include this field so that the original publisher is given credit. The format is simply doi: number such as doi: 10.5555/646360.690408
- Date of Update
  Include this only if it's different from the fields Year of Publication and Date of Publication. Eg. Updated 2019-07-23
  Typically this is relevant for blog posts, press releases, news articles or even tutorials that were first published but later updated with new or corrected information.
- Access Date
  This is the date when the online resource was accessed for research. Mentioning this date is useful information should the source become unavailable later. Eg. Accessed 2020-11-08
  This is not applicable for offline sources.
- URL
  This is the URL at which the source was accessed during research. This is not applicable for offline sources.
  Some websites include a canonical URL for each article but there's also a permanent link (aka permalink) that points to an exact version of the article. Most wikis including Wikipedia have this feature. Cornell's arXiv also has a specific URL for each article version. In such cases, use the permalink or the version-specific URL.
  Don't include targets in the URL, that is, ending with #target-name. Instead you can draw attention to the target in the citation. In fact, when using Google Search from Google Chrome, URLs sometimes contain targets of the form #:~:text=... that has to be excluded when formatting the reference.
  Suppose the source is a closed publication accessible only with a paid subscription. However, as a researcher you might have accessed it via another source such as an author's own website, Cornell's arXiv site, Sci-Hub, etc. In such cases, mention any of these latter sources. Credit to the original publisher is given via the DOI field.
For better verifiability from readers, authors are encouraged to select online sources. However, offline sources such as published books are allowed. For such offline references, omit the enclosing brackets [] and parentheses ().
When linking to the full citations inline with content, use parentheses within square brackets. Devopedia will transform this to suitable links and interactions for the reader. For example, "By the end of 2016, there were 10% more JavaScript programmers compared to 2015.[(Guardian 2016)]". In this example, [(Guardian 2016)] is the citation. You don't need to superscript this since Devopedia with handle the transformation automatically.
Sometimes a reference may have many sections or pages. To help readers verify the content quickly, enhance the citation with additional information on section/page/table/figure number. For example, say [(Bill et al. 2021, sec. 2.1)] rather than just [(Bill et al. 2021)]; say [(Howard and Hill 2000, pp. 324)] rather than just [(Howard and Hill 2000)].
Citations should ideally follow punctuation marks, such as comma, semi-colon or period. The placement of citations is important. A citation relates to the preceding text that can be either a clause, sentence, or paragraph. If two successive paragraphs are from the same source, give the same citation at the end of each paragraph. Suppose a paragraph has three sentences summarized from the same. Suppose citation is given only at the end of the first sentence. This is wrong since second and third sentences will be treated as uncited. Instead, move the citation to the end of the third sentence.
For content organized as a bulleted list, each list item can have a citation. Alternatively, citation can be at the end of the clause that introduces the list.

Sample Code

When including sample code, you need to mention the language so that syntax highlighting is done right. The following languages are supported:
4cs, 6502acme, 6502kickass, 6502tasm, 68000devpac, abap, actionscript, actionscript3, ada, algol68, apache, applescript, apt_sources, arm, asm, asp, asymptote, autoconf, autohotkey, autoit, avisynth, awk, bascomavr, bash, basic4gl, bf, bibtex, blitzbasic, bnf, boo, c, c_loadrunner, c_mac, caddcl, cadlisp, cfdg, cfm, chaiscript, cil, clojure, cmake, cobol, coffeescript, cpp, cpp-qt, csharp, css, cuesheet, d, dcl, dcpu16, dcs, delphi, diff, div, dos, dot, e, ecmascript, eiffel, email, epc, erlang, euphoria, f1, falcon, fo, fortran, freebasic, freeswitch, fsharp, gambas, gdb, genero, genie, gettext, glsl, gml, gnuplot, go, groovy, gwbasic, haskell, haxe, hicest, hq9plus, html4strict, html5, icon, idl, ini, inno, intercal, io, j, java, java5, javascript, jquery, kixtart, klonec, klonecpp, latex, lb, ldif, lisp, llvm, locobasic, logtalk, lolcode, lotusformulas, lotusscript, lscript, lsl2, lua, m68k, magiksf, make, mapbasic, matlab, mirc, mmix, modula2, modula3, mpasm, mxml, mysql, nagios, netrexx, newlisp, nsis, oberon2, objc, objeck, ocaml, ocaml-brief, octave, oobas, oorexx, oracle11, oracle8, oxygene, oz, parasail, parigp, pascal, pcre, per, perl, perl6, pf, php, php-brief, pic16, pike, pixelbender, pli, plsql, postgresql, povray, powerbuilder, powershell, proftpd, progress, prolog, properties, providex, purebasic, pycon, pys60, python, q, qbasic, rails, rebol, reg, rexx, robots, rpmspec, rsplus, ruby, sas, scala, scheme, scilab, sdlbasic, smalltalk, smarty, spark, sparql, sql, stonescript, systemverilog, tcl, teraterm, text, thinbasic, tsql, typoscript, unicon, upc, urbi, uscript, vala, vb, vbnet, vedit, verilog, vhdl, vim, visualfoxpro, visualprolog, whitespace, whois, winbatch, xbasic, xml, xorg_conf, xpp, yaml, z80, zxbasic
If a particular language is not supported, choose another language that you think will give suitable syntax highlighting.
On Collaboration

Don't contribute to content if you don't agree with the licensing that we follow at Devopedia. Any content that you provide can be freely shared and distributed in public domain. No individual owns the content at Devopedia.
Don't aim for perfection. Believe in the power of collaboration. It's okay if what you've written feels incomplete to you. Someone else will improve it. Don't try to impose your ownership on content. Welcome feedback and edits from others. Take an impartial view when reviewing other people's edits. Initiate discussion if you don't agree with those edits. Focus on the content. Explain your viewpoint.
For every edit, give a description of what and why the change was made. At Devopedia, this is called a Change Description. This description is important for other editors. Edit history of an article can be more meaningfully displayed when descriptive notes are included.
Every change is versioned. This includes uploaded media as well. Hence be bold but not reckless in your edits. It's always possible to revert to an earlier version.
When collaborating on content, any of the following may happen: rephrasing of content; updating code samples; adding alternative viewpoints to make the article more complete and neutral; deleting or merging of duplicate content; including citations; correcting factual mistakes; fixing of invalid links; improving the styling; rearranging content for better flow; resizing of media; removing or replacing of licensed material with alternatives compatible with Devopedia's licensing; spelling and grammar errors; and more.
Be civil and polite to other members. Respect their privacy. Give them freedom to express their viewpoints. Participate in good spirit in discussions. During discussions, thank others for their contributions. Give credit where it is due.
Welcome newcomers by guiding them through the authoring process. Point them to useful resources that make them comfortable at Devopedia. Mentor them. Try to understand their areas of expertise and suggest topics where they can contribute the most.
Don't indulge in or encourage confrontation. Strive for consensus. At Devopedia, consensus does not mean that everyone should agree. Consensus is implicit: no one objects to the edit.
Don't undo an edit just done by someone without good reason. If an article goes through repeated edits (edit wars), engage in discussion rather than carry on with the edits. Sometimes it may be a good idea to wait for things to cool off. Devopedia will lock the article in case of edit wars, until a consensus is reached via discussion.
For all article discussions, use the official article chat pages at Devopedia. Don't discuss offline via third-party apps, emails and others. For discussions not tied to a specific article, you can use Devopedia's GitHub webapp issues page.
Don't humiliate others or engage in personal attacks. Don't try to bring down others just because they didn't follow these guidelines. Try to see if there's a good reason why they didn't follow a guideline. Remember that guidelines can have exceptions.
It's important to participate in discussions, to be heard but also listen to what others have to say. Discussion also helps in building your reputation on Devopedia. Your reputation becomes important when community decides to nominate publishers who have extra privileges.
There's currently no formal mechanism to resolve disputes at Devopedia such as via a third-party mediation or community-wide polling. At the moment, disputes are resolved by individuals themselves via discussions. This is something the community can improve at a later point in time.
Good & Bad Examples

In this section, we give some bad examples of article content. We then give good examples of the same and explain why these are better. Examples are shown in Markdown syntax.
We start with examples that are applicable to multiple sections, typically Summary, Discussion and Milestones. After that, we give section-specific examples.
We hope authors will find these examples useful. By following these guidelines, you will produce high quality articles. Publishers will also have an easier time reviewing and approving your articles for publication.

General

All content must be unopinionated. The word "cool" in the following example is an opinion of the author. It's okay to do this if you can cite a source where it's discussed why it's cool. Instead we can say that the package has many useful features and go on to give further details.
Opinionated
Python has __Pandas__ for data preparation that has cool features.

Neutral
Python has __Pandas__ for data preparation that has many useful features such as multi-indexing, handling missing data and detecting outliers.

Don't try to be formal in your writing. Instead imagine you're talking to the reader. Prefer to use contractions. For example, say "don't" rather than "do not".
Too Formal
Let us take note of the fact that a bridge is also technically classified as a Tor node. However, bridges are not listed on the main Tor directory. What this implies is that ISP cannot easily block all bridges.

Simple Language
A bridge is also a Tor node but it's not listed on the main Tor directory. So your ISP can't easily block all bridges.

Spelling differs in U.S. and British English. We don't have a preference but use the same spelling within an article. In the following example, "modeling" is changed to "modelling" for consistency.
Inconsistent
R and many third-party packages are suited for data analysis and modelling. R simplifies the work of a data scientist by offering tools for easy data manipulation, visualization and modeling.

Consistent
R and many third-party packages are suited for data analysis and modelling. R simplifies the work of a data scientist by offering tools for easy data manipulation, visualization and modelling.

When expanding abbreviations, singular or plural form must be consistent in both the abbreviation and its expansion. For example, "Artificial Neural Networks (ANNs)" and "Artificial Neural Network (ANN)" are consistent expansions whereas "Artificial Neural Networks (ANN)" is not. However, it's correct to write "Institute of Electrical and Electronics Engineers (IEEE)" since the abbreviation is defined for the plural form.
Inconsistent Abbreviation
Artificial Neural Networks (ANN) are effective in scenarios where traditional ML methods such as regression, time series analysis or PCA cannot perform or forecast accurately.

Consistent Abbreviation
Artificial Neural Networks (ANNs) are effective in scenarios where traditional ML methods such as regression, time series analysis or PCA cannot perform or forecast accurately.

When embedding media, give a descriptive caption. The caption can be different from how the image was described in the source reference.
Missing Image Caption
![image](2682.1551149944.png "Source: Rahangdale 2018.[(Rahangdale 2018)]")

Image with Caption
![image](2682.1551149944.png "Comparing CSS Modules with other approaches. Source: Rahangdale 2018.[(Rahangdale 2018)]")

Content must be written in Markdown syntax. Direct use of HTML tags is not allowed.
Disallowed HTML
For example, a web app based on <div style="color:red; font-size:1.5em">MVC pattern</div> would include models, views and controllers.

Allowed Markdown
For example, a web app based on **MVC pattern** would include models, views and controllers.

To bring the reader's attention to important words, phrases or definitions, bold the text. Use emphasis styling for title of a book, name of an organization, etc. There's no strict rule where to use bold or emphasis. Authors can decide based on the context. Syntax for bold is ** … **. Syntax for bold is __ … __.
Lack of Styling
Claude Shannon publishes his paper titled "A Mathematical Theory of Communication". He introduces the word "bit" as a contraction of binary digit. He credits J. W. Tukey for coining this word.[(Shannon 1948, Introduction)]

Suitable Styling
Claude Shannon publishes his paper titled __A Mathematical Theory of Communication__. He introduces the word **bit** as a contraction of binary digit. He credits J. W. Tukey for coining this word.[(Shannon 1948, Introduction)]

Try to avoid custom styling for equations. For example, don't change the font size, colour, or background. Don't add border to the equation. Stick to default styles. This allows authors and readers to focus on the equation content rather than it's styling.
Custom Styling for Equations
$\bbox[red,2pt]{p/(1-p)}$ is the **odds ratio**. $\class{special}{\ln(p/(1-p))}$ is the **link function** or **logit function**. The output values from this function are called **logits**.

Default Styling for Equations
$p/(1-p)$ is the **odds ratio**. $\ln(p/(1-p))$ is the **link function** or **logit function**. The output values from this function are called **logits**.

Numbered lists are not supported. Use only unnumbered lists. Explicitly creating a numbered list will force each list item into a separate paragraph and result in too much space between list items.
Numbered List
Here are some data serialization formats:
1. **XML (Extensible Markup Language)** - Nested textual format. Human-readable and editable. Schema based validation. Used in metadata applications, web services data transfer, web publishing.
2. **CSV (Comma-Separated Values)** - Table structure with delimiters. Human-readable textual data. Opens as spreadsheet or plaintext. Used as plaintext Database.
3. **JSON (JavaScript Object Notation)** - Short syntax textual format with limited data types. Human-readable. Derived from JavaScript data formats. No need of a separate parser (like XML) since they map to JavaScript objects.

Unnumbered List
Here are some data serialization formats:
    * **XML (Extensible Markup Language)** - Nested textual format. Human-readable and editable. Schema based validation. Used in metadata applications, web services data transfer, web publishing.
    * **CSV (Comma-Separated Values)** - Table structure with delimiters. Human-readable textual data. Opens as spreadsheet or plaintext. Used as plaintext Database.
    * **JSON (JavaScript Object Notation)** - Short syntax textual format with limited data types. Human-readable. Derived from JavaScript data formats. No need of a separate parser (like XML) since they map to JavaScript objects.

Nested lists are not supported. Where it's necessary to create an inner list, write it inline.
Nested Lists Not Supported
    * This is item 1.
    * This is item 2.
        * This is item 2.1.
        * This is item 2.2.
        * This is item 2.3.
    * This is item 3.

Flat List
    * This is item 1.
    * This is item 2. (a) This is item 2.1. (b) This is item 2.2. (c) This is item 2.3.
    * This is item 3.

Don't overuse lists. Use lists only when each item is distinct and needs a short explanation. Otherwise, a comma-separated list of items is sufficient.
Just a List
Container orchestration has the following concerns:[(Isenberg 2016, slide 17)]
    * **Service Management**
    * **Scheduling**
    * **Resource Management**

Readable Flow
Container orchestration has three main concerns of Service Management, Scheduling, and Resource Management.[(Isenberg 2016, slide 17)]

List Items with Explanations
Container orchestration has the following concerns:[(Isenberg 2016, slide 17)]
    * **Service Management**: Labels, groups, namespaces, dependencies, load balancing, readiness checks.
    * **Scheduling**: Allocation, replication, resurrection, rescheduling, rolling deployment, upgrades, downgrades.
    * **Resource Management**: Memory, CPU, GPU, volumes, ports, IPs.

Summary

GPRC's official website provides a definition of GRPC. At Devopedia, we prefer explanations over definitions. In this example, we also show Wikipedia's introduction to GRPC, which is heavy on technical jargon. At Devopedia, we instead try to set the context and then introduce GRPC. If a reader gets lost in the Summary, it's likely that he will skip the rest of the article.
Definition (GRPC Homepage)
A high performance, open-source universal RPC framework.

Technical Jargon (Wikipedia Intro)
gRPC (gRPC Remote Procedure Calls) is an open source remote procedure call (RPC) system initially developed at Google. It uses HTTP/2 for transport, Protocol Buffers as the interface description language, and provides features such as authentication, bidirectional streaming and flow control, blocking or nonblocking bindings, and cancellation and timeouts. It generates cross-platform client and server bindings for many languages. Most common usage scenarios include connecting services in microservices style architecture and connect mobile devices, browser clients to backend services.

Giving Context and Explanation
Tightly integrated monolithic applications of the past gave way to modular design. With the growth of the Internet, different parts an application could reside in different servers and accessed over the network using what we __Remote Procedure Call (RPC)__. With the advent of cloud computing, applications are composed of microservices. These microservices are loosely integrated but their interfaces are precisely defined using APIs.[(LeClaire 2017)]
gRPC is a framework that enables the implementation of highly scalable and performant application whose parts are distributed over a network. The framework abstracts away the low-level networking details from app developers so that they can focus on the application logic. Developers need not worry about how one part calls a functionality in another remote part. gRPC takes care of this and enables more responsive real-time apps.[(Marculescu 2015)]
**gRPC** is a recursive abbreviation that expands to **gRPC Remote Procedure Call**.[(Smith 2017)]

The following example is about "Confusion Matrix". We see that the summary is good but too brief. A beginner who's not familiar with classifiers will be lost. The improved text provides background context in the first paragraph. Then it describes how such a matrix can be constructed. It ends with a summary of important facts on this topic.
Too Brief
A confusion matrix is a table that is often used to describe the performance of a classification model (or "classifier") on a set of test data for which the true values are known.[(Markham 2014)]
Thus, it helps in investigating the performance of a model.[(Idris 2018)]

Giving Context and Description
In statistical classification, we create algorithms or models to predict or classify data into a finite set of classes. Since models are not perfect, some data points will be classified incorrectly. Confusion matrix is basically a tabular summary showing how well the model is performing.
In one dimension, the matrix takes the actual values. The matrix then maps these to the predicted values in the other dimension. In reality, the matrix is like a histogram. The entries in the matrix are counts. For example, it records how many data points were predicted as "true" when they were actually "false".
Confusion matrix is useful in both binary classification as well as multiclass classification problems. There are many performance metrics that can be computed from the matrix. Learning these metrics is handy for a statistician or data scientist.

When writing the summary, follow a structure. Here are some suggested structures: (a) problem, solution, example, current status (b) what, why, relevance (c) context, explain, define, example. Keep in mind that summary must give readers a basic understanding of the topic and convince them to read the rest of the article. The following example is about "Docker" but the summary is too brief. It focuses on the difference between containers and VMs. In the improved text, we first introduce containers. In the second paragraph, we describe Docker. In the last paragraph, we mention important details.
Unstructured
Docker is a tool that runs the applications in a containerized platform with more resource efficiency rather than running the applications in a virtual machine with guest operating system consuming more resources.
Dockers doesn't need any Guest OS to run the containers since it uses the same process of base OS.

Structured Flow
![image](8323.1565281088.png "Docker architecture. Source: van der Mersch 2016.[(van der Mersch 2016)]")
A container is a standard unit of software that packages an application with all of its dependencies and libraries. This makes it easy to deploy applications within containers regardless of hardware configuration or operating system. Unlike virtual machines, containers use the host OS rather than bundling an OS with the application.[(Opensource 2019)]
Docker is a container platform. It provides a complete ecosystem of tools to build container images, pull these images from known registries, deploy containers, and manage or orchestrate running containers across a cluster of machines. Docker has popularized container adoption. Even the phrase "dockerize my app" has become common.[(Docker 2019a)]
The word "Docker" usually refers to its engine. The commercial offering is called __Docker Enterprise__. There's also the free community edition that's simply called __Docker Engine__. Docker was initially available on Linux but later become available on MacOS and Windows as well.[(El Amri 2018)]

Discussion

Questions should be really a question and not a statement.
Not a Question
* Technical Details of ImageNet

A Proper Question
* Could you share some technical details on ImageNet?

A "what is" question on the topic is usually answered in the Summary section. Instead, we should explain the topic is greater detail in Discussion.
Too General
* What is ImageNet?

Question Seeking Details
* How has ImageNet advanced computer vision?

Questions must include contextual keywords. For example, "where is it useful?" has no context unless we know what "it" refers to.
Lacking Context
* Where is it useful?

Question with Context
* What are the use cases where SQLite is a suitable database?

Milestones

Milestones must be written in present tense, as if the reader is reading it in the year it happened. Events that happened earlier to that month and year can be in past tense.
Past Tense
* Apr 2012
Samsung released **Tizen**, an OS that can be used on a wide range of embedded devices including smartphones.[(AppFutura 2018)] The first smartphone came out in India in January 2015, the Samsung Z1.[(Russell 2015)]

Correct Tense
* Apr 2012
Samsung releases **Tizen**, an OS that can be used on a wide range of embedded devices including smartphones.[(AppFutura 2018)] The first smartphone comes out in India in January 2015, the Samsung Z1.[(Russell 2015)]

One-line milestones are usually not interesting to read. Try to include more details. Instead of just saying what happened at a specific date, give some context as to why this happened or how it advanced the state of the art. Milestone description might start by relating to an earlier milestone.
Too Brief
* 1971
David Huffman and Max Clowes independently publish **line labelling algorithms**.[(Zdziarski 2018)]

Milestone with Context
* 1971
Research in computer vision continues in the direction suggested by Roberts. David Huffman and Max Clowes independently publish **line labelling algorithms**. Lines are labelled (convex, concave, occluded) and then used to discern the shape of objects.[(Zdziarski 2018)]

Milestones can be made interesting by including historical images, some of which may be well known, particularly to those who are working in that domain.
Just Text
* 1875
Francis Galton creates a correlation diagram to analyze the relationship between the sizes of mother and daughter sweet-pea seeds.[(Friendly and Denis 2001, 1850+: Correlation)]

Including an Interesting Image
* 1875
![image](5620.1523706784.jpg "Francis Galton's correlation chart. Source: Friendly and Denis 2001, 1850+: Dot map of disease.[(Friendly and Denis 2001, 1850+: Correlation)]")
Francis Galton creates a correlation diagram to analyze the relationship between the sizes of mother and daughter sweet-pea seeds.[(Friendly and Denis 2001, 1850+: Correlation)]

Evolution of a topic can be seen as an evolution of multiple subtopics. Rather than create multiple milestones for a subtopic, it's easier to club them into a single milestone. This also makes it easier for readers to follow the timeline of the entire topic. The following example is about the article "Mock Testing" and its subtopic "Google Mock".
Multiple Milestones of a Subtopic
* Dec 2008
Google releases **Google Mock**, a mocking framework for C++.
* 2013
Version 1.7.0 of Google Mock is released.[(Google Mock GitHub 2015, Releases)]
* 2015
Google Mock is absorbed into the GoogleTest project.[(Google Mock GitHub 2015)]

Single Subtopic Milestone
* Dec 2008
Google releases **Google Mock**, a mocking framework for C++. Version 1.7.0 is released in 2013.[(Google Mock GitHub 2015, Releases)] In 2015, this is absorbed into the GoogleTest project.[(Google Mock GitHub 2015)]

Sample Code

The first word after ``` is the language to be used for syntax highlighting. This name is also displayed on the tab containing the code. To display a more readable name, start a sample code with the syntax ```langName displayName, as shown in the two examples below.
Unusual Naming
```csharp
some code here ...
```
```cpp
some code here ...
some code here ...
```

Readable Names
```csharp C#
some code here ...
```
```cpp C++
some code here ...
some code here ...
```

The display on the tab need not be the name of a programming language. For example, for an article on "Secure Coding with Python", it's not useful to display "Python" on all code samples, although all of them are highlighted according to Python syntax. It's more useful to show names that describe the nature of the code. Don't use spaces in these descriptive names.
Language Naming
```python Python
some code here ...
```
```python Python
some code here ...
some code here ...
```

Descriptive Naming
```python Input
some code here ...
```
```python String-Formatting
some code here ...
some code here ...
```

Sometimes authors may give multiple code samples written in the same language. Rather than display the language name, give a name that's descriptive. In the following code samples, the display names would be "React" and "Composition".
Only Language Names
```javascript
some code here ...
```
```javascript
some code here ...
some code here ...
```

Descriptive Names
```javascript React
some code here ...
```
```javascript Composition
some code here ...
some code here ...
```

Always give attribution to the source and date of access. Notice too in this example that we don't have syntax highlighting for GraphQL. Hence, we approximate it with Sparql syntax highlighting.
No Attribution
```sparql GraphQL
# Schema
type Student {
  id: ID
  firstName: String
  lastName: String
}
```

With Attribution
```sparql GraphQL
# Source: https://fullstackmark.com/post/17/building-a-graphql-api-with-aspnet-core-2-and-entity-framework-core
# Accessed 2019-05-22

# Schema
type Student {
  id: ID
  firstName: String
  lastName: String
}
```

References

When a reference has a single author, name should follow the format of lastName, firstName.
Wrong Syntax for Single Author
* [Robin Rendle. 2017. "Does CSS Grid Replace Flexbox?" CSS-Tricks, March 31. Accessed 2019-05-27.](https://css-tricks.com/css-grid-replace-flexbox/)

Correct Syntax for Single Author
* [Rendle, Robin. 2017. "Does CSS Grid Replace Flexbox?" CSS-Tricks, March 31. Accessed 2019-05-27.](https://css-tricks.com/css-grid-replace-flexbox/)

Sometimes websites don't disclose the author's name. In such cases, use the website's name instead.
Wrong Author Name
* [Editor. 2010. "All too much." The Economist, February 27. Accessed 2019-05-20.](https://www.economist.com/special-report/2010/02/27/all-too-much)

Website Name as Author Name
* [The Economist. 2010. "All too much." The Economist, February 27. Accessed 2019-05-20.](https://www.economist.com/special-report/2010/02/27/all-too-much)

If the reference is a YouTube channel, use the channel's name rather than just "YouTube". If the presenter's name is available and the content can be attributed to that person, you may use that name.
Using Platform Name
* [YouTube. 2018. "CSS Grid Explained Quickly (with diagrams and code)." January 07. Accessed 2019-05-27.](https://www.youtube.com/watch?v=ojKbYz0iKQE)

Using User or Channel Name
* [Statuscode. 2018. "CSS Grid Explained Quickly (with diagrams and code)." Statuscode, on YouTube, January 07. Accessed 2019-05-27.](https://www.youtube.com/watch?v=ojKbYz0iKQE)

When there are two or more authors, only the first author's name is in syntax "lastName, firstName". Other names should be written as "firstName lastName". Separate the last author's name from the previous author's name with " and ". In the following example, that reference has three authors.
Wrong Syntax for First Author, Missing " and "
* [Tim Mackinnon, Steve Freeman, Philip Craig. 2001. "Endo-testing: unit testing with mock objects." Published in Extreme programming examined, pp. 287-301, Addison-Wesley Longman Publishing Co., Inc. Accessed 2019-03-20.](https://www2.ccs.neu.edu/research/demeter/related-work/extreme-programming/MockObjectsFinal.PDF)

Correct Syntax for Multiple Authors
* [Mackinnon, Tim, Steve Freeman, and Philip Craig. 2001. "Endo-testing: unit testing with mock objects." Published in Extreme programming examined, pp. 287-301, Addison-Wesley Longman Publishing Co., Inc. Accessed 2019-03-20.](https://www2.ccs.neu.edu/research/demeter/related-work/extreme-programming/MockObjectsFinal.PDF)

There are many online platforms where content is not static. Content is edited by multiple authors and often revised. In this case, use the website's name for author's name instead of individually naming each author.
Changing Authorship
* [bot, mdnwebdocs-, wbamberg, jswisher, chrisdavidmills, jensimmons, be47liberty, dvincent, and kdubb. 2019. "CSS Grid Inspector: Examine grid layouts." Mozilla Developer Network, March 23. Accessed 2019-05-27.](https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Examine_grid_layouts)

Use Website Name
* [MDN Web Docs. 2019. "CSS Grid Inspector: Examine grid layouts." Mozilla Developer Network, March 23. Accessed 2019-05-27.](https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Examine_grid_layouts)

It's possible that an author has authored multiple papers in the same year. If these are referenced in the same Devopedia article, we'll need to disambiguate. We use alphabet suffixes in lowercase to do this.
Wrong Disambiguation
* [Microsoft Docs Arch. 2018. "Architecture." Advanced Concepts and Internals, Xamarin.Android, April 25. Accessed 2018-08-21.](https://docs.microsoft.com/en-us/xamarin/android/internals/architecture)
* [Microsoft Docs JNI. 2018. "Working With JNI." Java Integration, Xamarin.Android, March 09. Accessed 2018-08-21.](https://docs.microsoft.com/en-us/xamarin/android/platform/java-integration/working-with-jni)

Use of Suffix to Disambiguate
* [Microsoft Docs. 2018a. "Architecture." Advanced Concepts and Internals, Xamarin.Android, April 25. Accessed 2018-08-21.](https://docs.microsoft.com/en-us/xamarin/android/internals/architecture)
* [Microsoft Docs. 2018b. "Working With JNI." Java Integration, Xamarin.Android, March 09. Accessed 2018-08-21.](https://docs.microsoft.com/en-us/xamarin/android/platform/java-integration/working-with-jni)

Sometimes a website has subdomains. Use subdomain name rather than just the website name for author name. In the following example, "Katalan Studio" is acceptable for author name but it's better to say "Katalan Studio Docs".
Ignoring Subdomain
* [Katalan Studio. 2018. "Test Listeners (Test Hooks)." Katalon Studio, June 08. Accessed 2018-07-11.](https://docs.katalon.com/pages/viewpage.action?pageId=5126383)

Naming by Subdomain
* [Katalan Studio Docs. 2018. "Test Listeners (Test Hooks)." Katalon Studio, June 08. Accessed 2018-07-11.](https://docs.katalon.com/pages/viewpage.action?pageId=5126383)

Reference text enclosed with square brackets must end with a period.
Missing Ending Period
* [Hudak, Paul. 1989. "Conception, evolution, and application of functional programming languages." ACM Computing Surveys,Vol. 21, No. 3, pp. 359–411, September. Accessed 2017-04-05](http://www.jdl.ac.cn/turing/pdf/p455-floyd.pdf)

Ending Period
* [Hudak, Paul. 1989. "Conception, evolution, and application of functional programming languages." ACM Computing Surveys,Vol. 21, No. 3, pp. 359–411, September. Accessed 2017-04-05.](http://www.jdl.ac.cn/turing/pdf/p455-floyd.pdf)

Title of the reference article should be enclosed in double quotes. The title should also end with a punctuation. If the title includes a puncutation, keep it. Otherwise, append a period at the end.
Missing Period in Source Title
* [Santiago, Antonio. 2014. "7 reasons to use Yeoman's angular-fullstack generator" DZone, October 26. Accessed 2019-06-27.](https://dzone.com/articles/7-reasons-use-yeomans-angular)

Correct Formatting of Source Title
* [Santiago, Antonio. 2014. "7 reasons to use Yeoman's angular-fullstack generator." DZone, October 26. Accessed 2019-06-27.](https://dzone.com/articles/7-reasons-use-yeomans-angular)
* [Bering, Nicholas. 2017. "TypeScript for Small Projects, Too!" June 17. Accessed 2019-04-08.](https://nicholasbering.ca/jekyll/2017/06/17/typescript-for-small-projects-too/)

In the following examples, author names are mentioned but the website name has been omitted. We should correct this by acknowledging the website as well. Sometimes, a blog such as ITNEXT is hosted on a blogging platform such as Medium. We should acknowledge both of them.
Missing Website Name
* [Nwamba, Chris. 2016. "Create A Custom Yeoman Generator in 4 Easy Steps." July 10. Accessed 2019-06-27.](https://scotch.io/tutorials/create-a-custom-yeoman-generator-in-4-easy-steps)
* [Bill, Matthew. 2019. "Generating code with Yeoman js." Medium, January 27. Accessed 2019-06-27.](https://itnext.io/generating-code-with-yeoman-js-f13e0da87374)

Acknowledging Website Name
* [Nwamba, Chris. 2016. "Create A Custom Yeoman Generator in 4 Easy Steps." Scotch.io, July 10. Accessed 2019-06-27.](https://scotch.io/tutorials/create-a-custom-yeoman-generator-in-4-easy-steps)
* [Bill, Matthew. 2019. "Generating code with Yeoman js." ITNEXT, via Medium, January 27. Accessed 2019-06-27.](https://itnext.io/generating-code-with-yeoman-js-f13e0da87374)

The date of publication of the reference must be included. If only month is available, include only the month. If this information is not displayed on the webpage, you may be able to see it when you search the HTML source of the page. Look for keywords "created" or "published" in the source. Sometimes an article is updated after it's published. Include the date of update. Finally, it's important to mention when the article was accessed or retrieved for research.
Missing Dates
* [Cui, Yan. 2015. "Why I like Go's interfaces." The Burning Monk. Accessed 2017-12-29.](http://theburningmonk.com/2015/05/why-i-like-golang-interfaces/)
* [Dutton, Sam. 2012. "Getting Started with WebRTC." HTML5 Rocks, July 23. Accessed 2018-02-16.](https://www.html5rocks.com/en/tutorials/webrtc/basics/)
* [Nvidia. 2016. "Deep Learning Frameworks." Nvidia, April 5. Updated 2017-02-09.](https://developer.nvidia.com/deep-learning-frameworks)

Including Dates
* [Cui, Yan. 2015. "Why I like Go's interfaces." The Burning Monk, May 11. Accessed 2017-12-29.](http://theburningmonk.com/2015/05/why-i-like-golang-interfaces/)
* [Dutton, Sam. 2012. "Getting Started with WebRTC." HTML5 Rocks, July 23. Updated 2014-02-21. Accessed 2018-02-16.](https://www.html5rocks.com/en/tutorials/webrtc/basics/)
* [Nvidia. 2016. "Deep Learning Frameworks." Nvidia, April 5. Updated 2017-02-09. Accessed 2017-02-20.](https://developer.nvidia.com/deep-learning-frameworks)

Citations

Item name in citations is optional. Item names help in narrowing the source to a specific item, section, page, figure, table, etc. This makes it easier to verify content from its source. We give two examples to illustrate this.
Without Item Name
![image](8350.1528442883.jpg "A webpage can be composed from modular self-contained parts. Source: Fink 2016.[(Fink 2016)]")
EDA helps us to uncover the underlying structure of the dataset, identify important variables, detect outliers and anomalies, and test underlying assumptions.[(Filliben and Heckert 2003)]

With Item Name
![image](8350.1528442883.jpg "A webpage can be composed from modular self-contained parts. Source: Fink 2016, slide 8.[(Fink 2016, slide 8)]")
EDA helps us to uncover the underlying structure of the dataset, identify important variables, detect outliers and anomalies, and test underlying assumptions.[(Filliben and Heckert 2003, sec. 1.1.1)]

Sometimes Devopedia may combine one or more images into a single image or edit an existing image before using it. When citing, add the phrase "Adapted from ".
Ignoring Edits
![image](6562.1520446230.png "MAC data and ACK frames, along with details of Frame Control Field. Source: National Instruments 2017, figs. 6-8.[(National Instruments 2017, figs. 6-8)]")

Mention "Adapted from "
![image](6562.1520446230.png "MAC data and ACK frames, along with details of Frame Control Field. Source: Adapted from National Instruments 2017, figs. 6-8.[(National Instruments 2017, figs. 6-8)]")

In the following example, two paragraphs are based on the reference. However, author has included citation only at the end of the second paragraph. This is not obvious to readers. Citations have paragraph-level scope. It's better to include the citation for each paragraph.
Multiple Paragraphs
In Data Science, the scientific process is similar except that the use of data and algorithms becomes central to the process.
The process starts with an interesting question, often aligned to business goals. Available data is then cleaned and filtered. This may also involve collecting new data as relevant to the question.[(Gutierrez 2014)]

Paragraph-Level Citations
In Data Science, the scientific process is similar except that the use of data and algorithms becomes central to the process.[(Gutierrez 2014)]
The process starts with an interesting question, often aligned to business goals. Available data is then cleaned and filtered. This may also involve collecting new data as relevant to the question.[(Gutierrez 2014)]

A single paragraph may be a summary from multiple sources of reference. Instead of citing them together, cite them in the right places. Merging citations is allowed but use them only when necessary.
Merged Citations
Ionic 2 can also allow access to native API but will require the use of Apache Cordova. Xamarin uses native UI components and offers good performance.[(Zia 2017)][(Cruxlab 2017)]

Fine-Grained Citations
Ionic 2 can also allow access to native API but will require the use of Apache Cordova.[(Zia 2017)] Xamarin uses native UI components and offers good performance.[(Cruxlab 2017)]

When content is written as a list of items, we can include citations for each item list. If all list items are from the same source, this becomes repetitive. Include citation only when introducing the list. However, if a specific list item comes from another source, add citation for that item.
Repetitive Citations
For basic network security, do the following:
    * Disable broadcast of SSID to prevent casual folks from trying to connect to your access point.[(ICO UK 2017)]
    * Disable DHCP and allocate IP addresses to a limited range.[(Griffith 2016)]
    * Reduce the range of the Wi-Fi signal but a hacker will probably use a higher gain antenna.[(Griffith 2016)]

Hierarchical Citations
For basic network security, do the following:[(Griffith 2016)]
    * Disable broadcast of SSID to prevent casual folks from trying to connect to your access point.[(ICO UK 2017)]
    * Disable DHCP and allocate IP addresses to a limited range.
    * Reduce the range of the Wi-Fi signal but a hacker will probably use a higher gain antenna.
Research Tips

Research is extremely important so that authors get the facts right. Even when an author is experienced and knowledgeable in a particular topic, research is necessary since content must be cited from published sources. This helps readers, reviewers and other authors verify the content if they wish to do so.

Sources

The first point of research is to do an online search based on relevant keywords or simply the title of the article you're going to write. Start with Google Scholar for peer-reviewed publications.
Another useful research tool is Elicit. Like Google Scholar, it gives links to technical publications along with paper titles and excerpts from paper abstracts.
Complement Google Scholar with search engines such as Google and Bing.
Search engines allow us to search under the "Images" category. This may uncover useful webpages not otherwise ranked highly via a general search. Depending on the licensing used, you may be able to use the images as well with attribution. Likewise, we can search under "Videos" category.
Conversational interactions are becoming common on the web. Two useful tools are OpenAI's ChatGPT and Google's Bard. These are powered by AI models. They give answers directly rather than returning a list of search results. But they don't give the sources. This makes it difficult to use them effectively. Despite these limitations, these tools can speed up preliminary research and help a researcher identify the important questions for an article.
Primary sources of research include original research publications, books or official documentation. For example, if the topic is related to Django, Django's official documentation site is a primary source. Reading, understanding and summarizing primary sources is often not easy and time consuming.
Secondary sources of research include tech blogs, news articles, video tutorials, Wikipedia articles, and so on. Often these sources are easier to read and understand. However, it's important that these should be reputable sources. For example, an article published on The Guardian or WIRED magazine are reputable sources. An answer in Quora with no upvotes is perhaps not a good source. An article on Medium is perhaps a good source provided that article has got plenty of claps.
Primary sources are preferred over secondary sources. Only when primary sources are not accessible or hard to understand, authors should fallback to secondary sources.
It's hard to define what are bad sources. Use your discretion. Typically, these display lots of ads and popups. The quality of writing is poor or misleading. Sites that adopt ghost writing and where content is mostly unverified by the editors are unreliable. Content whose authors are not subject matter experts may not be suitable sources. The following sources are seen as sub-standard and authors should avoid them:
data-flair.training, educba.com, edureka.co, geekflare.com, geeksforgeeks.org, guru99.com, javatpoint.com, journaldev.com, simplesnippets.tech, simplilearn.com, techvidvan.com, tutorialspoint.com, w3schools.com
Some publications adopt predatory publishing, that is, take money from authors to publish sub-standard content that's not properly peer-reviewed. Use your judgement to spot such publications. Avoid these are reference sources.
Wikipedia can be a useful shortcut. If your topic has a page on Wikipedia, go to the References section of the article. Links in that section can be a great starting place for your research, provided the Wikipedia article is well-written.
Research is an iterative process. Start with some sources. As you start reading them, they may cite or quote from other sources. Those sources themselves might be important or interesting, and you may want to study them as well. As you start writing, you may notice some knowledge gaps. More research would be needed to plug those gaps.

Queries

When doing an online search for relevant content, these keywords may help: intro, basics, primer, survey, tutorial, getting started, docs.
To cover the topic in depth, these keywords may help: features, benefits, adoption, case studies, tools, techniques, best practices.
When writing about the topic, cover both sides of the argument. These keywords may help: benefits, features, advantages, pros and cons, problems, limitations, limits, myths, criticism.
In some articles, we may do comparisons. Use these keywords find relevant webpages: compare, alternatives, open source.
For Milestones section, these keywords may help: history, milestones, timeline, evolution, origins, roadmap. Sometimes we wish to cover recent history. To uncover such results, search engines allow us to search under the "News" category. When talking about software, often searching with these keywords help: releases, versions, experimental, deprecated.
To get to lecture notes and course material from reputed colleges, add any of these terms to the main search query: edu pdf, course notes, class slides

Author Guidelines

Overview

How-To Guides

External Resources

Login