Appropedia:Content guidelines

Appropedia allows many types of content as long as it aligns with the vision and mission. This page describes the most common types, as well as their use cases.

Appropedia is not an encyclopedia, but a compendium of knowledge to solve planetary problems, mostly from a human-centered perspective: poverty, climate change, conservation, health, education, etc. Appropedia focuses mostly on open know-how, which means that knowledge documented tries to help people and organizations understand, study and reproduce actions, to create an effect in their immediate environment.

Page length[edit | edit source]

Pages of less than 1000 characters are generally considered too short and are categorized as stubs. Stubs need expansion, but good stubs are still valuable. They may contain a good definition, one or more key insights, and/or a very valuable link.

Conversely, pages of more than 100,000 characters are generally considered too long. Such pages should be summarized or split in two or more pages. One efficient way to proceed is to move the largest section into its own page, write a good lead section, and leave an excerpt behind.

Sections[edit | edit source]

• Avoid sections of level 1 (with a single = sign). Level 1 should be reserved for the page title only.
• Avoid sections of level 5 or 6 (with 5 or 6 = signs). Sections nested too deep are generally confusing. Restructure the content to avoid them, or move the entire section to a new page and leave an excerpt behind.

Lists[edit | edit source]

• Avoid nesting lists more than two levels. They can be confusing and don't look good on mobile devices.
• Use ordered lists only when the order of the items matters, for example when giving step-by-step instructions. Use unordered lists otherwise.

Types of content[edit | edit source]

Appropedia can also be described as a library of technical knowledge, and as such, is varied and used in different ways. Here are some of the most common page types on Appropedia and how to find them on Appropedia.

Topic pages[edit | edit source]

Topic or knowledge pages are usually intended to help readers expand their knowledge about a specific subject. They can relay knowledge, but they are not encyclopedic articles. They must provide the following:

• A general overview of a concept, technology, skill or procedure.
• A starting point to introduce the general concepts of a subject, subdivisions and other considerations.
• Lists of examples and most common cases in the literature, including cases on Appropedia that may serve guide research on the subject or the selection of a technology to replicate.

Readers may use a topic page as a useful resource to explore the variety of use cases and experiences documented on Appropedia about a technology or a procedure.

Structure[edit | edit source]

Check that a topic (or knowledge) page complies with the following criteria:

• All topic pages must contain the Template:Page data databox.
• Overview (describe the subject)
• Instances on Appropedia (list of examples on Appropedia). For devices and projects, you can use Template:Search to display a gallery.

Guidelines[edit | edit source]

To create a stellar topic page, consider the following:

• Technical considerations such as how they are built, alternatives and difficulties associated to its use.
• Cultural considerations
• Environmental considerations.
• External documentation sources.

Some of the best practices for writing a knowledge-based article are:

1. aim for brevity - users are looking for a simple answer, not a poem;
2. makes reading easier - split long blocks of text by adding lists, titles, and graphics;
3. add assets - sometimes a photo, video or link turns out to be a faster response (consider using content from Wikimedia Commons);
4. test and optimize - reshape content based on user feedback until there is a decrease in the number of questions.

Literature reviews[edit | edit source]

Literature reviews list a summary of sources and commentary on a subject. Literature reviews on Appropedia are usually connected to a specific project that aims to develop or implement a specific method or technology. Despite being fairly personal (and messy) documents created during research, keeping documentation of the research process is a very valuable asset for future researchers to find relevant literature and to understand the reasoning behind design decisions for a project. They serve as an invaluable resource to understand the reasoning behind a specific project or design and produce verifiable information that can be reused in the future.

Literature reviews are the heart of how Appropedians research. It involves looking for source material such as papers, patents, and other second-hand information. This is where researchers show their knowledge of the subject they're researching. A literature review is a discussion of existing material in the subject area. Therefore, it will require a collection of published works (printed or online) related to the selected research area.

Structure[edit | edit source]

Literature reviews that are part of a project or device page must be placed as a subpage, for example at DIY masks/literature review.

• Template:Page data with parameter type=Literature review.
• List of sources and references.

Guidelines[edit | edit source]

The preparation of a literature review includes several steps which can be traced back to three phases as described below:

• 1st phase - Preparation of a literature review
  • Choose the topic, define the problem and formulate the question.
  • Identify and select the items to include.
  • Select the citation model
  • Organize the included items.
  • Summary tables of data extraction for analysis.
  • Development of a concept map
• 2nd phase - Write the revision
  • Introduction.
  • Central body of the revision.
  • Conclusions.
  • Citations and references
• 3rd phase - Check the revision
  • Content review
  • Write the review in good style

Check Category:MOST literature reviews for a guide on how to make literature reviews.

Devices and projects[edit | edit source]

These pages usually describe a specific instance of a technical implementation, either through the design or construction of a specific, or by implementing a project on a specific setting. To understand the difference between both categories, it is important to note that while many projects on Appropedia involve the construction of a device, they do not require it as they may use social or environmental methods and techniques. The possible use cases are:

• Project pages that do not require the construction of a device. Examples are community-based projects (clean up projects, activism), disaster response and relief projects and others that involve mostly persons, having tools and technology as a secondary resource.
• Project pages that involve the construction and deployment of devices. An example would be the study of how rocket stoves were built and used in a community.
• Device pages which contain the bill of materials, assembly instructions and other resources needed to replicate it.

Structure[edit | edit source]

• Template:Project data to describe the context under which the device was built.
• Template:Device data with references to its technical files and other resources to reproduce.
• Template:Page data with a description of the documentation authors.

Basic documentation

• Overview
• Photo of finished device
• Bill of materials
• Assembly instructions
• Downloadable files.

Guidelines[edit | edit source]

• Regional considerations: Such as climate, locating raw materials, etc, as well as cultural, social and political context.
• Bill of materials: a list of materials, quantities and costs required to replicate a device.
• Status tagging: For project pages it is important to note the status. Often the investment cost of recreating or building an appropriate technology is high. There must also be a successful history of implementation before an investment in time and resources to employ an innovation can be made. By following the instructions on the page Appropedia:Status, the status of a particular appropriate technology can be shown easily to help users decide on the use of a device, or whether more work is needed before deployment. See Appropedia:Status for details.
• Assembly instructions: there must be adequate information and schematics for a user to trust that there is due diligence in a given design and that the designed device can perform to specifications. For example:
• Simple how-to sections for building or using a technology or material
  • Product name and general description of the device, its intended use, and intended users.
  • How does the device work? Has it been proven?
  • If it is going to be used in combination with other devices, describe how.
  • General description of the functional elements, e.g. components (software, if applicable).
  • Include visual representations (photos, drawings, diagrams, etc.), clearly indicating components and explanations for a better understanding of the visual material.
  • Technical specifications such as dimensions, etc.
• The most effective contents of an organization are visual ones. For this reason it is recommended to use visual material to communicate documentation. We recommend to see OSHWA's best practices. See a list of devices on Appropedia here: Category:Devices

Ported pages[edit | edit source]

Structure[edit | edit source]

• Mark original material as ported-from
• Check copyright licenses and permissions: Before you want to publish a photo, article, etc. you need to verify what you can share, re-use, or copy with a license that is compatible with the ones allowed on Appropedia.
• We recommend editing content to fit the format on Appropedia. This will allow content to be more easily reutilized by others.

Guidelines[edit | edit source]

• You can upload as raw images or documents. A scanner, however, can't do what OCR software does, a scanner isn't enough to extract the relevant information and transform it into a Word format for editing. All it is able to do, in fact, is to create an image of the document, that's nothing more than a set of white and black or colored points (raster graphics). The OCR technology is able to recognize the characters present in the image and transform them into words to edit them.
• We recommend porting using an Optical Character Recognition (OCR) technology. This allows you to transform different types of documents, such as digital photos or PDF files into editable texts very quickly and, above all, effortlessly, into editable formats.

Skill pages[edit | edit source]

Skill pages describe and exemplify how to do something. It shows the description of a series of steps that others can learn, by using text or video. This refers to all how-tos and tutorials aimed at transferring know-how in different settings, such as education and international development. Skill-based content can take various forms on Appropedia, for example, technical briefs (publication by) and books (ported literature).

Structure[edit | edit source]

• Page data
• Course data
• Video with annotations

Guidelines[edit | edit source]

• Make videos as short as possible.
• Accompany all media content with text-based instructions to ensure portability into other formats and accessibility for people without good bandwidth, small screens; as well as visual or language barriers.

Course pages[edit | edit source]

These contain collections of pages organized into learning modules

Structure[edit | edit source]

• Navigation data
• Course data
• Page data
• Syllabus

External links[edit | edit source]

Appropedia welcomes suitable external links, even commercial ones. Suitable links are those where the emphasis is on is on design & technical info directly relevant to the page, rather than promotion of a product or organization.

Making documentation[edit | edit source]

Appropedia has a set of tools and page types that can be used to describe a variety of things, ways of building these things, and experiences. These are designed to be adapted to different types of projects and to ensure their reproducibility and openness by teaching others the necessary knowledge and skills to understand, adapt and execute them.

Documentation is useful for a variety of situations and processes, for example: brainstorming ideas and idea mapping, designing a device, executing a project, or doing research. The community of Appropedians document real-world experiences by using the most common page types, or by combining them. For example, a nonprofit looking to co-create a new type of rocket stove for a community might research previous solutions through a literature review, test out designs and document their design files and assembly instructions on a device page, document how the construction went out with a project page, and create a step-by-step list of instructions on a skill page. We hope that Appropedia can serve all these purposes.

For this reason, we have considered the typology of hardware documentation, which considers elements such as instructions, design files,^[1][2] as well as of other types of projects such as the ones present in international development documentation.

These guidelines apply only to the main namespace (unless otherwise specified in the guideline).

See also[edit | edit source]

• Help:Types of content
• Appropedia:Toolbox contains a description of the tools that can be combined to create different types of documentation.

References[edit | edit source]