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.
VisitorVisitor is someone who accesses the content without logging into the site. Visitors may be permitted to anonymously like or share content.
AuthorAuthor refers to anyone who creates and edits content.
EditorEditor is an author who is also authorized to edit content created by others. By default, all authors are promoted to the status of editors.
PublisherPublisher 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.
ContributorContributor is a term collectively applied to authors, editors and publishers. Collaborator is an alternative term.
ReviewerReviewer is a contributor who participates in discussions on articles. Reviewers comment on articles with a view towards improving them.
UserUser is a term collectively applied to anyone who uses Devopedia. This includes contributors and visitors.
MemberMember 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.
DeveloperDeveloper 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 Life Cycle
An article can be in one of four states as depicted in Figure 2:
New DraftWhen a new article is created, it enters this state. The article is not stored on the server until it is submitted. Hence a new draft remains within the context of the browser of the author creating it.
UnpublishedOnce 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.
LockedWhen 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.
PublishedThis 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.
An article may in future be allowed to enter Archived or Deleted states. Currently these states are not supported. Once published it will remain published. Publishers may choose to unpublish an article in exceptional circumstances. Note that this action will break links pointing to the unpublished article.
With reference to Figure 2, the transitions are as follows:
- When a new article is submitted from a web browser, it is saved for the first time on the server. It thus moves from New Draft to Unpublished state.
- 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.
- 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. Publishers may also move an article from Published to Unpublished state.
- 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.
- 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.
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.
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 synonymous with what you have in mind. In such cases, it's better to redirect the new article to the existing one. Such redirection can be easily specified when editing an article.
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.
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 the use of 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 use of expressions that gives 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.
Devopedia is not the place to publish original research. You may refer to externally published sources that show original research and results.
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.
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.
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. Alternatively, you can upload the media to Devopedia.org and then link to them within the article. When doing so, mention the source for correct attribution.
When linking to external video, the following sites are supported: YouTube, DailyMotion, Vimeo. Don't link to URLs streaming live video.
Give every media a suitable caption. Name the media file suitably.
For all uploaded media, limit the size to 250 KB (image), 2.5 MB (audio) and 25 MB (video).
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 be titled as "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.
Organize content into a narrative flow. An article must have the following parts:
SummaryThis 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.
DiscussionRather 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.
MilestonesThis 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 12 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 CodeSome 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.
ReferencesThis 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.
See AlsoThis 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 ReadingThis 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.
Top ContributorsTo recognize the contributions of authors, this section lists the top contributors for the article. Contributors are ranked based on the number of words they have contributed to the current or any older version of the article. The word count is weighted by the length of time the words have been visible on the page before a newer version replaced them. Votes from the article's discussion channel are also considered.
Article StatsThis section is automatically generated by the Devopedia backend system. 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.
Recent NewsThis section is automatically generated by the Devopedia backend system. 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.
ResourcesThis section is automatically generated by the Devopedia backend system. 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.
Word count includes all words visible on the web browser, including captions to media. This means that HTML tags are not counted. 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.
Where it makes sense, use unnumbered lists in the description section; arrange content into named sections as noted earlier; do not introduce extra sections; embed or link to media compatible with our licensing.
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".
You must associate one or more primary tags with every article. Currently the following primary tags are defined:
WebArticles 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.
MobileArticles related to mobile development will be tagged here. Example include Android, React Native, MIT App Inventor, app store, and more.
EmbeddedExamples of articles here are RTOS, MCU, ASIC, serial interface, endianness, Harvard architecture, firmware, soft real time, and more.
DesignDesign 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.
LanguagesThe 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.
ToolsThis 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 of MSDN.
DataThis 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.
AlgorithmsThe 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".
NetworkingNetworking 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.
SecurityThis 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.
TestingDifferent types of testing will have their article page. Examples include unit testing, regression testing, performance testing, and more. Methodologies of testing and development would include Agile testing and Test-driven Development.
SystemSystem aspects usually not considered by a traditional developer would come here. This might 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 and Style Conventions
Write in plain English as far as possible. This means avoid using technical jargon except when it relates directly to the article. Use short sentences of 15-20 words. Prefer active verbs rather than passive verbs. For example, say "throw an exception" rather than "exception must be thrown". Avoid the use of noun forms of verbs. For example, say "tests may fail" rather than "tests may result in failures". Don't try to be formal in your writing. Instead imagine you're talking to the reader. Prefer the use of contractions. For example, say "don't" rather than "do not".
For titles, use normal sentence case. For example, say "Web browser" rather than "Web Browser". Titles are usually nouns or noun phrases.
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.
For citations, use the Chicago Manual of Style. While there are many alternatives, the Chicago Manual of Style is as good as any. For the sake of consistence across all articles, Devopedia adopts this style. Since this style has two variants, use the author-date system. Study the examples by following the preceding link.
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 acronym. 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."
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.
When entering content, anything that does not correspond to the article's standard structure (described earlier) will be stripped out by Devopedia.
You may use tables in content. 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.
Use HTML's <blockquote>...</blockquote> to style short memorable text quoted from external sources. This will be rendered bigger to make it stand out. Ensure the quote is at the end of a paragraph or on a paragraph by itself. Cite the source when using such quotes. Blockquote is allowed only within sections Summary, Discussion and Milestones.
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 rather than https://www.mozilla.org/en-US/firefox/.
Mathematical equations can be included in content. MathJax is used for this purpose. The default math delimiters are $$...$$ and \[...\] for displayed mathematics, and \(...\) for in-line mathematics. Please consult MathJax documentation for full details.
When including sample code, you need to mention the language so that syntax highlighting is done right. The following languages are supported:
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 Version Note. 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.