Help Guide for Contributing to BEMcyclopedia
Interested in contributing content to BEMcyclopedia? Sharing your knowledge can help BEM practitioners hone their skills and apply BEM effectively on their projects. This section of the site will get you up to speed on how to create new pages, add to and refine existing pages, and ensure that the content is properly organized within the structure of the site. Thanks for joining the BEMcyclopedia community!
Getting Started
Who can contribute?
Contributions may only be made by users who have created and logged into an account. Currently, the site is in beta and editing rights are limited to only approved account holders but editing will be open to all users soon! User edits will not go live immediately - a quality review will be performed before posting edits. This is to ensure that information has been vetted, and to limit spam on the website. Do not post anything that is copyrighted or offensive - it will be taken down immediately. Additionally, any user that posts content that is self-promotional may have the content removed or have their editing access restricted. Refer to the terms of use and disclaimers for more information.
Creating an account and requesting editing rights
Create an account by clicking the link at the top of this page. After you have created an account, send an email with your username to admin@bemcyclopedia.com. Our team will grant you editing rights.
Software neutrality
Content on this site is not designed for a specific BEM software. To the extent possible, please try to create content that can generally be useful to users of a wide variety of BEM software tools. We recognize that some images of software outputs and graphics may be specific to a particular software, so if you include these, be sure to focus your discussion on what the outputs or graphics are conveying and how this is useful to the project (rather than describing how to generate the graphic from that particular software). And also, be sure you created those graphics or have permission to post them!
Summary of site organization
The website is organized into two main sections: Learn by Design Task, and Essential BEM Concepts.
Learn by Design Task
The main concept of this section of the site is to organize educational resources around a typical building design project’s timeline. This is done by first identifying the major design phases of the project. Then, within each design phase, we have identified several design objectives, i.e., what the design team must accomplish during this phase. Finally, for each design objective, we identified the BEM tasks that may help to inform that specific design objective.
The main page for this section includes a navigation index organized according to this concept. By expanding the sections of the index, one can drill down to more detailed pages related to each design phase, and detailed tutorials for the various BEM tasks. The main index is not user-editable (it is only editable by site administrators to ensure that the site's organization principles are not changed). However, user-created tutorials can be added to this index without the help of site admins. More details on how to organize pages nicely in the index are provided in the "best practices" section of this help guide.
"Design Phase" Pages
Clicking on the title of any of the design phases in the index will bring you to a more detailed page about that particular design phase. Each design phase page begins with a short description summarizing what the design team is trying to accomplish during this phase. Then the page is divided into several sections, each of which represents a design task or design objective that is typically being worked on during the given project phase.
Each of the design objective sections begins with short description of the objective. The description aims to give the reader insight into what decision the design team is trying to make. Then, a bulleted list of BEM tasks is presented. These tasks are activities that a BEM practitioner can perform to help the design team carry out the specific design objective.
"BEM Task" Pages
These are the detailed tutorials that provide guidance on how BEM practitioners can help to inform the various design tasks that occur throughout the life of a project. These pages should clearly describe what design decision may be informed by the BEM analysis, what analysis activities should be performed, and how the information might be shared with the design team in a meaningful way. More information about the type of information and organization of the BEM task tutorials is provided below in the best practices section of this help page.
Essential BEM Concepts
This section is a collection of general BEM knowledge, and fundamental skills that apply to a variety of BEM tasks. There are subsections that discuss principles of building science (how buildings work in the real world) so that modelers have a better understanding of how the models relate to these principles; there are also numerous subsections that provide guidance on how to create models at varying levels of detail depending on what stage of design the project is in; there is guidance on how to interpret simulation results (by relating the results back to the building science principles), and how to present the results effectively; and there is guidance on various time-saving approaches such as automation and scripting. Many of the "BEM tasks" in the "Learn by Design Task" section will link to additional information within the Essential BEM Concepts section of the site.
The main page for this section includes a navigation index organized by the main subsections. By expanding the sections of the index, one can drill down to more detailed pages related to each subsection, and detailed tutorials for many concepts. The main index is not user-editable (it is only editable by site administrators to ensure that the site's organization principles are not changed). However, user-created tutorials can be added to this index without the help of site admins. More details on how to organize pages nicely in the index are provided in the "best practices" section of this help guide.
Glossary Pages
Some pages may just be simple definitions of BEM, design, building physics, or other terms commonly encountered by BEM practitioners. These pages do not need to be structured and organized like in the Learn by Design Task and Essential BEM Concepts pages. But, they are often useful to be included as links within the detailed tutorials on this site.
Editing pages
Editing an existing page
Editing an existing page can easily be done by clicking either the "edit" or "edit source" buttons. If you are not logged into your account, the edit buttons do not appear.
The "edit" button lets you edit pages using a convenient editing interface with numerous formatting tools built in (similar to a word processor). The "edit source" button lets you directly edit the page's source code in wikitext format.
Pages can either be edited all at once, or you can edit specific sections. The benefit of editing a specific section is that this approach allows for multiple editors to work on different sections of a single page without their edits conflicting.
Using the editor
The editor (called "Visual Editor") is a feature of the MediaWiki software that lets users conveniently create and edit pages using a word processor style interface. An overview of the controls are provided in the thumbnail to the left. More details about how to use features of the Visual Editor are provided in the sections below. Additional help can be found on the MediaWiki Visual Editor user guide.
Editing the source code (wikitext)
Pages can also be created and edited using source code in a format called wikitext. Wikitext allows for a great deal of customization, formatting, and special controls that are not all available in the Visual Editor, however it requires a fair bit of knowledge to use effectively. Most of the information on this help page is geared around using the Visual Editor, but there are some advanced use cases where you may wish to edit the wikitext directly such as formatting tables, or inserting "template" information. Wikitext also includes limited support for using html tags.
Additional help can be found on the MediaWiki Wikitext help page.
Describing your edits
When you click the button to save your edits, you will be prompted to type a short summary of what you edited. Keep it brief (one line) but descriptive. This will help your fellow editors see what changes have been made since they last worked on the page.
Adding sections to a page
Sections are a nice way of organizing the contents of a page into... sections. If sections are given meaningful titles, then readers can easily navigate the page. Another benefit of breaking up the page into sections is that the section names appear in the page's table of contents.
To create a new section, select the desired heading level from the text style menu (refer to the thumbnail to the right). If there is already text on the line you are editing when you change the text style, then this text will become the section title. If you are on a blank line, then any new text you write will become the section title.
Note that after "sub-heading 2", there is very little or no visual difference in lower level sub-headings. As a general rule, try not to go "too deep" in section hierarchy as it tends to overcomplicate the contents.
Note in the image to the right that using sections will nicely organize the page's table of contents.
As a final note, one of the text styles in the drop down menu is called "page title" although you can not actually change the title of a page while in the editor. Do not use this page title style to format other text on the page. If you really want to rename a page, see below for guidance.
Adding a table of contents
By default, a table of contents (sometimes abbreviated to TOC) is automatically generated on a page when more than three section headings are used. If your page has fewer than 3 section headings, you can force the addition of a TOC. This is done by choosing "page settings" from the "Options menu" as shown in the thumbnail.
It is also possible to remove the table of contents from a page although this is strongly discouraged. Some of the navigation pages have the TOC removed because navigation is designed directly into the page and the TOC is superfluous in these cases.
As noted above, the TOC is automatically organized based on the titles of of headings and sub-headings.
Inserting images
Images are strongly encouraged! Graphical representations of inputs and outputs are very important to understanding BEM concepts.
When inserting images on a page, we recommend inserting them as thumbnails. They will be inserted to the right of the text section where the insertion occurred, and text will wrap around the thumbnail. From a page layout standpoint, it is preferred to use thumbnails rather than directly inserting the full size image. Clicking on a thumbnail will still allow users to expand and view the image at full size.
To insert the image, select the option "Images and media" from the "Insert" menu. This will open a dialog box where you can either search for an image that has already been uploaded to BEMcyclopedia (e.g. if you like an image you see on another page and wish to reuse it elsewhere), or you can upload your own images. If you are uploading your own image, you must acknowledge that it is your own work and you have the rights to share it. You can drag an image file into the upload window, or select a file from your computer. As part of the upload process, you will be prompted to add a name to the image (usually the same as filename but if the filename is not descriptive, then give the image a meaningful name), and a description of what the image is. Finally, you will be prompted to add a caption which will appear with the image thumbnail (this caption can be changed later in the Visual Editor).
Inserting tables
The Visual Editor only has the ability to insert rudimentary tables. This can be done by opening the "Insert" menu and selecting "Table" but the tables are very limited in terms of formatting. If you wish to create a more visually interesting table (with highlighted cells, different colors, etc.) this can be done using the wikitext (source code) editing approach. There are some good (and free) online tools available that let you design interesting tables using a web interface and then export the table into wikitext which you can then cut and paste into your pages source code. Here is a good example website where this can be done: https://www.tablesgenerator.com/mediawiki_tables
Linking to other pages
A powerful feature of a wiki is linking to other pages on the site with related content. We strongly encourage using links within tutorials and other pages so that readers can dig deeper into related topics.
Links to other BEMcyclopedia pages
Adding links is very easy. While in editing mode, select the text on your page that you wish to turn into a link, then select the "link" button from the toolbar. This will pop up a window which allows you to search for the page on BEMcyclopedia that you wish to link to. The search will automatically search for the text you highlighted, but it is possible (and often likely) that the BEMcyclopedia page name won't match exactly. In this case, you may wish to search for it using other terms, or, if you already know the name of the page you wish to link to, then you can just enter it here. Note that the search feature is case-sensitive so be careful about using capital letters. Also, note that the highlighted text in your page (that you are turning into a link) does not necessarily need to match the full name of the linked page, as long as you connect them properly.
Links to external websites
Adding links to external websites is very similar. Select the text you wish to turn into a hyperlink, select the "link" button from the toolbar, then select "External site" in the pop-up window and paste the URL of the site you wish to link to. Note that you must paste a complete URL here (including the http:// prefix). The best way to get the full URL is by opening the page you wish to link to and copying its full URL from your browser's address bar.
Adding references/citation
Give credit where credit is due! If you have relied on other sources as you research a topic, be sure to add citations for all references. Citations should be added at the end of a sentence or paragraph that relies on external research materials. If you want to know more about how/when/why to cite a source, refer to Wikipedia's article on the topic.
To add the citation (while in editing mode), move your cursor to the point where you wish to add the citation, and select "Cite" from the toolbar. This will open a drop-down menu where you can select the type of source (e.g. website, journal, etc.). When you select the source type, a pop-up window will open that prompts you to enter information about the source such as title, authors, date of publication, etc.
If you reference a source more than once on a page, the "Cite" menu provides an option to "reuse" a previously referenced source (so you don't need to enter its information again).
Adding the list of references to the bottom of a page
If your page has citations, then you should add a list of the references to the bottom of your page. First, create a new Heading called "References" as the last section of your page. Then, from the "Insert" menu, select "References list" and this will insert the list onto your page.
Adding categories to a page
The organization of this website is largely dependent on using categories appropriately. This section describes how to add a category to a page, but please be sure to read the section below on using categories properly to keep the site organized. Don't add categories to any pages without reading that first!
To add a category, select the "hamburger" options menu and then select "Categories." This will pop up a window where you can select an appropriate category to assign to the page. The search bar allows you to find an appropriate category. If you type a name of a category that does not exist, then you have the ability to create a new category with that name. But, before you add any new categories please be sure you understand the site's category assignment best practices!
After you have successfully assigned a category to a page and saved your edits, you will see a list of the page's categories at the very bottom of the page.
Creating new pages
New pages can be created a few different ways.
- Link to a page that doesn't yet exist - if you are creating an overview page about (for example) modes of heat transfer and wish to add a more detailed page about conduction, you can go ahead and add a link to a page titled Conduction to your overview page. When you save your edits after adding the link, it will appear in red font. This red font indicates that you have linked to a page that does not exist (whereas links to existing pages will appear in blue font). If you click the red link, you will be brought to a page and asked if you wish to create the new page titled Conduction.
- Type name of page in address bar - every page's title appears in your browser's address bar after the url (bemcyclopedia.com/wiki/index.php/TITLE). If you replace TITLE with the name of the new page you wish to create, then you will be brought to a page and asked if you wish to create the new page with this title.
- Type name of new page in search bar - if you search for a page title that doesn't exist, the search results page will give you the option of creating the new page. Before creating the new page, just be sure that a similar page does not already exist with a different title.
For additional information and guidance for creating new pages refer to the following links:
- MediaWiki help guide on creating new pages
- Working with MediaWiki website guide on creating new pages
Renaming and redirecting pages
Pages are not really renamed on a wiki. If you wish to change a page's title, then you will actually be "moving" it to a new page address. Be careful when doing this - it is possible, and quite likely, that other pages have already linked to the original page's title. If you do move the page to a new address, you will be prompted whether you wish to redirect from the original title to the new title - if you do this, then page links will not break, so please do it! However, first consider whether you actually need to rename the page in the first place. If a page exists titled "Air conditioner", then do you really need to rename it as "air conditioning unit"? Probably not! In many cases, it is preferable to redirect an alternate title to the pre-existing page title rather than moving the existing page to a new title.
Deleting pages
Deleting pages is disabled for all users except for administrators. Deleting is generally to be avoided as it will likely break links from other pages. Administrators reserve the right to delete any pages that are spam, or delete specific sections of spam content. If you feel that a page needs to be deleted, please contact the website's administrators. (this link will open a page to send an email. Search for user name BEMAdmin and fill in the email form). Be sure to include a link for the page you wish to be deleted along with an explanation.
As noted above in the section summary of site organization, much consideration has been put into organizing the site's contents into the two main groups to allow for intuitive navigation. The main homepage of the site and the overview pages for Learn by Design Task and Essential BEM Concepts have been protected (restricted to read-only) to ensure that the site navigation remains unaltered. However, there is still the ability to add newly created pages to the indexes (described below) so that they appear nicely organized in the overview pages. If you wish to propose changes to the protected navigation pages, see below for guidance.
This website is intended to be under constant maintenance and development. We expect that, over time, it may make sense to add new sections or make other types of modifications to the navigation. As noted above, this functionality is currently restricted to site administrators only. However, if you wish to propose a new section, just send an email to the user BEMAdmin using this link. Be very specific about the proposed changes. Please note that there is nothing restricting you from going ahead and creating new pages for your desired topic area. Feel free to create the content and organize it as you please (e.g., using a navigation page with links to your new content). We will work with you to integrate it into the main site navigation after you have contacted us with your request.
Using categories properly to keep site organized
As noted above in the section summary of site organization, the main overview pages for Learn by Design Task and Essential BEM Concepts each have a detailed index of pages, organized according to design phase (in the case of Learn by Design Task) or main subject area (for Essential BEM Concepts). These indexes are automatically generated by assigning appropriate categories to each page.
Choosing the right category
Theoretically, you could assign any and all categories to a page, but then that page would appear in every section of the index and the index wouldn't be very useful for navigation. There may be some cases where it makes sense for a page to appear in a couple sections, but please try to limit the number of categories assigned to the page. If you want the page to appear in both the Learn by Design Task and Essential BEM Concepts sections, this is also possible but make sure it really makes sense to do this.
In essence, the categories exist in a hierarchical tree structure that aligns with the website's index pages. Familiarize yourself with these category trees as described below.
Learn by Design Task categories
The category tree for Learn by Design Task pages can be found here. The structure of the tree is identical to the index on the Learn by Design Task page. It is organized first by major design phases of the project. Then, within each design phase, subcategories exist for design objectives. These design objectives categories are the ones you should be applying to your tutorials (aka BEM tasks tutorials). You'll note that by expanding the tree (by clicking the little arrow) will show a list of all the pages assigned to that design objectives subcategory. You'll also note that the design phase categories are NOT assigned to the tutorial pages. Take a moment to browse the category tree before deciding how to categorize your page.
Essential BEM Concepts categories
Similarly, the structure of the Essential BEM Concepts category tree is identical to the index on the Essential BEM Concepts page. It is organized according to this section of the website's main topic areas. As noted above, assign the lowest level subcategories to your pages to maintain the functionality of the website's index. The example in the adjacent thumbnail shows several tutorial pages assigned appropriately to the "Envelope Inputs" subcategory (not to the parent "Input Tutorial" category).
Experimental categories
There are a few experimental sets of categories being considered for future addition to the website. We have developed a category tree for designating tutorials according to ASHRAE Standard 209. In the future, we may introduce a new navigation view that lets users navigate based on the ASHRAE 209 cycles. These categories have not been widely applied to the tutorials, but please feel welcome to do so!
Another category under consideration is user type (i.e., are the pages targeted towards architects, engineering practitioners, researchers, etc.). If you think this would be a valuable addition, please let us know by sending an email to the user BEMAdmin using this link.
Best practices - Learn by Design Task
These tutorials are primarily focused on teaching users how to apply a model for use on a specific design task. The tutorial should not teach you how to build a model, but rather how to take a model and use it to test different design options. The nuts and bolts of how to build a model is covered in the "Essential BEM concepts" section of the website and can be referenced by many other task-specific pages. Here is a practical example of how the content is intended to be separated between the two sections of the website.
In the Conceptual Design phase, many design analysis tasks are likely to start with an early-stage, simple box model and then test different design alternatives on that model. One study may analyze different window-to-wall ratios, another may analyze the building's orientation. For the example of the building orientation analysis, the tutorial page starts by telling the user to "create a simple box model" and simply providing a link to the simple box model tutorial (under the Essential BEM concepts section of the site). Now, within the orientation analysis page the tutorial can focus on how to use that simple box model by modeling it with different rotations, shading features, etc. The tutorial should really focus on giving the user advice ("try these options," "test these parameters over this range," "consider combining this feature with another EEM," and so forth). The simple box model tutorial can be used over and over again across many of the conceptual design tutorials, but the specific manner in which the simple box model is used and advice to the modeler is likely to vary and can be tailored for each design task analysis.
As a general rule, if you find yourself needing to explain how to model something, it should go in the "Model Inputs" section. Similarly, if you find yourself needing to explain a building science concept, it should go in that section. The benefit of splitting that content from the "Learn by Design Task" tutorials is that it can be generalized and reused across many different tutorials by linking. Then the Learn by Design Task section can really focus on applying the knowledge to a specific design task.
Best practices - Essential BEM concepts
These tutorials are focused on teaching users basic concepts about buildings, building science, and BEM software concepts. They are not intended to teach users how to analyze specific design concepts within the building design process, but rather to give users the necessary knowledge prior to analyzing project-specific design concepts. It is intended that these best practices will be useful to a large number of "Learn by Design Task" tutorials and therefore will be included as links within the design task tutorials.
As an example, if a "design task" analysis is being performed to analyze window to wall ratio, then links to "Essential BEM concepts" tutorials relating to how to create window geometry, how to perform parametric analysis, and building science tutorials related to window conduction and solar heat gains would be very useful to include to help users understand how to perform the design task, and how to analyze the results. These "essential concepts" might also be useful to include for other design tasks such as shading analysis, building orientation analysis, and many others.
As a general rule, try to make the "Essential BEM concepts" tutorials as generic as possible - they should not be focused on a specific design analysis, but rather general enough to be useful in understanding many different design task analyses. In other words, keep these Essential concepts broad - if there is something that is very specific to a certain design task, then that content can go in the "Learn by Design Task" section.
| Content is available under the Creative Commons Attribution-ShareAlike License; additional terms may apply. By using this site, you agree to the Terms of Use. |