Item:OSW3d31fba2cdab4da0aa7de038df8bd96d: Difference between revisions

no edit summary
(Add attachment)
Tag: Metadata slot edit
No edit summary
Line 69: Line 69:
=== How to get started ===
=== How to get started ===
This is a temporary workspace for writing how-to guides.
This is a temporary workspace for writing how-to guides.
Welcome to the Battery Knowledge Base. This guide assumes no prior knowledge to wikis or ontology, the two main technologies the Battery KB is built upon. The guide will first direct you through some basic actions before giving a more theoretical explanation of how the Battery KB works. First, you need to make an account.


==== How to create an account ====
==== How to create an account ====
# You need an account to make changes to the Battery KB.
# You need an account to make changes to the Battery KB.
# If you have an ORCID as a researcher, then you can use that to set up your account. Your ORCID will become your username
# Click on the lower left "profile" icon and click Log in. You will be presented with a Username and Password field.
## If you have an ORCID as a researcher, then you can use that to set up your account. Your ORCID will become your username. Click the "Login with your ORCID Account" button and follow the instructions. (You will need to log into ORCID and then authorize the Battery KB to have access to your ORCID account information.)
## Afterwards, each time you need to log in again, click the same ORCID login button.
# If you don't have an ORCID, you need to contact an administrator. Unfortunately, there is currently [as of 2024-08-15] no other automated option to obtain an account without ORCID. Sorry!
# Finished! Once you are logged in, clicking on the "profile" icon in the lower left will open up a new menu with more options, including a link to your user page, preferences, contributions, and logging out.


==== How to change your user page from your ORCID: ====
==== How to change your username from your ORCID to a real name: ====
# Click on the three dots on    the right-hand side of the page.
You'll notice that your ORCID has become your user name, which is not useful for others to know who you are.
# Click on Move Page.
# Click on the lower left "profile" icon and click Preferences.
# Enter the desired name of    your user name.
# Under Basic Information, there is a field called "Real name:". You can type in the name which best identifies you.
# Click Move page.
# Scroll to the bottom and click Save.
# Finished!
# Finished!
# Note: the old page will still    exist, but will simply redirect to the new page.
# Note: if you make a mistake,    you can undo the move. Either move the page back or go the history of the    page and click Revert.
# Note: if you edit the user page, you will get a warning about editing a page for an account that doesn't exist.
# Note: unfortunately, this doesn't fix the user name used in the recent changes and contributions log.


==== How to make yourself a User entity in the Battery KB (not the same as above): ====
==== How to make yourself a User Entity in the Battery KB (not the same as above): ====
You are now a proper user for editing the Battery KB, but you also need to exist as an User Entity in the Battery KB. This page object reflects who you exist as in reality.
# Go to this page: [[:Category:OSWd9aa0bca9b0040d8af6f5c091bf9eec7]]
# Go to this page: [[:Category:OSWd9aa0bca9b0040d8af6f5c091bf9eec7]]
# At the top, click + Create.
# At the top, click + Create.
#Fill in the parameters where relevant and required.
#Fill in the parameters where relevant and required. At a minimum, first name and last name. Note: you might not be able to find your organization yet. Don't worry, if so, that's an exercise for later.
# Save your entity and starting using it! You can now essentially tag or define yourself in relation to other objects. For example, try finding your Battery 2030+ project and adding yourself as a Member to that project.
# Save your entity by clicking Save in the top right!
 
==== How to add your User entity to a project: ====


==== How to add your User Entity to a project: ====
As a User Entity in the Battery KB, you can now essentially tag or define yourself in relation to other objects. For example, try finding your Battery 2030+ project and adding yourself as a Member to that project by doing the following steps.
# Find your project. You can use search or this Category: [[:Category:OSWb2d7e6a2eff94c82b7f1f2699d5b0ee3]]
# Find your project. You can use search or this Category: [[:Category:OSWb2d7e6a2eff94c82b7f1f2699d5b0ee3]]
# Click on that Project's name to find their entity page.
# Click on that Project's name to find their entity page.
# At the top, there are two edit buttons: '''Edit data''' and '''Edit'''.
# At the top, there are two edit buttons: '''Edit data''' and '''Edit'''.
## '''Edit data''': this allows you to modify the parameters of the project entity. Essentially, it allows you to update the project's relationship to other objects, such as you being a member of the project.
## '''Edit data''': this allows you to modify the parameters of the project entity. Essentially, it allows you to update the project's relationship to other objects, such as you being a member of the project.
## '''Edit''': this allows you to modify the information displayed on the project's entity page.
## '''Edit''': this allows you to modify the information displayed on the project's entity page, like Project Overview.
# Click on Edit data and scroll down to find the Member info box.
# Click on Edit data and scroll down to find the '''Member''' info box.
# Click the + sign to add a new node.
# Click the + sign to add a new node.
# Type in your name in the search box and click on the right entry from the search suggestions.  
# Type in your name in the search box and click on the right entry from the search suggestions.  
## Troubleshooting: if you can't find your name, that means you didn't create yourself as a User entity first. You need to do that before adding yourself to a project. No, you cannot simply type in your name for now (you will learn how to do this later).
## Troubleshooting: if you can't find your name, that means you didn't create yourself as a User Entity first. You need to do that before adding yourself to a project. No, you cannot simply type in your name for now (you will learn how to do this later).
# Click Save.
# Click Save.
# Finished! Note: it may take some time for the changes are reflected on the page. You can try refreshing and purging the cache by using Shift+F5.
# Finished! Note: it may take some time for the changes are reflected on the page. You can try refreshing and purging the cache by using Shift+F5.
# Next steps: notice anything that you couldn't add to your User entity parameters because the objects didn't already exist? Go to those Categories and start creating those entities. For example, you can check for whether the BatteryKB already has your institution as an Organization entity here:[[:Category:OSW1969007d5acf40539642877659a02c23]]
# Next steps: improve the quality of your User entity. Here is an example a good quality User entity: [[Item:OSW72e733f317ef4cf9b8ca53e906c9acb9|Simon Clark]].


==== How to add your User entity to an organization: ====
==== How to add your User Entity to an organization: ====
You can add yourself to an organization (typically, your employer but also other types of organizations like workgroups or research groups like Battery 2030+). But this is done differently from a Project.
You can add yourself to an organization (typically, your employer but also other types of organizations like departments or smaller units like research groups). But this is done differently from adding yourself to a Project.
# Find your organization. You can use search or this Category: [[:Category:OSW1969007d5acf40539642877659a02c23]]
# Find your organization. You can use search or this Category: [[:Category:OSW1969007d5acf40539642877659a02c23]].
# Click on that Project's name to find their entity page.
## Does your organization not exist? We can solve that by creating your organization as an Entity in the Battery KB. Firstly, we should know what kind of organization you belong to. We have the following existing categories:
### Research Organization: research institutes that are not education-focused [[:Category:OSW789dcd084860478dbc60361a2da7c823]]
### Educational Organization: universities and such [[:Category:OSW9d63242855e44ab8b26d6ad9792a67b3]]
### Corporation: industrial organizations [[:Category:OSW5f4a3751d23e482d80fb0b72dcd6bc31]]
### Organization: a general category for things that don't fit in the above [[:Category:OSW1969007d5acf40539642877659a02c23]]
### Go to the category your organization most fits and click +Create on that page to create a new Entity, just like you did for your User Entity.
### Fill in the usual information. Note that acronyms go under the field Short Name(s). But this parameter field doesn't show up by default.
#### Click the "select properties" button at the top.
#### Scroll down to find the "Short name(s)" field and click the checkbox. Click outside of the small menu to close it.
#### A new field box named "Short name(s):" is now in the Data-Editor window.
#### Click on the + to create a node and type in the acronym/short name of the organization.
# If your organization already exists, click on that Organization's name to find their entity page.
# At the top, there are two edit buttons: '''Edit data''' and '''Edit'''.
# At the top, there are two edit buttons: '''Edit data''' and '''Edit'''.
# Click on Edit data and scroll down to find the Member info box.
# Click on '''Edit data''' and scroll down to find the '''Member''' info box.
# Click the + sign to add a new node.
# Click the + sign to add a new node.
# Type in your name in the search box and click on the right entry from the search suggestions.
# Type in your name in the search box and click on the right entry from the search suggestions. You can't just write your name, you need to find your '''User Entity''' to add.
# Click Save.
# Click Save.
# Finished!
# Finished! To review: to add your Organizational affiliation, go to '''your User Entity''' and add it there. To associate yourself with a Project, go to '''the Project Entity''' and add yourself to the '''Member''' field there.
# Troubleshooting: Should you use Member vs. Member Of? What's the difference?
# Should you use '''Member''' vs. '''Member of''' in the Project Entity
## '''Member person(s)''': if you want to associate yourself or your institutional affiliation with a Project, note that you go to the Project and Edit data there, '''not''' Edit data on your entity. [Actually, does it matter?]
## '''Member''': if you want to associate yourself or your institutional affiliation with a '''Project''', note that you go to the '''Project''' and '''Edit data''' there, <u>''not''</u> '''Edit data''' on your '''User Entity'''. That field simply doesn't exist for a '''User Entity'''. Ontologically speaking, '''Members/User Entities''' are a part of a '''Project''', but the reverse isn't true: '''Projects''' are ''<u>not</u>'' a feature or parameter of any '''User Entity'''.
## '''Member Of''': if you want to associate yourself to your institutional affiliation, you edit your entity page. If your organization belongs to a larger organizational unit, then you edit your organization's entity page. If you put the organization as a '''Member Of''' the project (this shouldn't be allowed anyway, but you may be confused as to why), it means your project would own your organization (which probably isn't true).
## '''Member of''': If your organization belongs to a larger organizational unit, then you can edit your organization's entity page to show that it is a '''Member of''' the larger organization. If you put the organization as a '''Member of''' the project (this shouldn't be allowed anyway, but you may be confused as to why), it means your project would own your organization (which probably isn't true). However, a '''Project''' might be a '''Member of''' a larger family of projects.
## In summary, Projects add members to ''their'' data, but Users add affiliation to ''their'' data.
 
## Ontologically speaking, it shouldn't matter and the properties should go both ways.
==== How to understand the Battery KB: ====
You should now have a proper '''User Entity''', which has both '''Project'''  and an '''Organization''' '''Entities''' to which it is related as a '''Member'''. At this point, it's good to explain how the Battery KB is a little different.
 
# The Battery KB is a "wiki" very much like Wikipedia, in the sense that every page is open for editing by all Users.
# The Battery KB is <u>''not''</u> like Wikipedia because of its underlying ontological framework. This makes is harder for Users to understand how to edit and contribute compared to Wikipedia.
# ''What is ontological framework?'' Simply put, this means essentially that '''everything''' is classified as a categorical entity with defined relationships to other objects, and ''nothing'' should exist outside of this framework.
# That means, compared to other wikis where you might simply create a page by writing on a blank slate and then link it to other places, you first instead go the '''Category''' to which that '''Entity''' would belong and create it from there along with defining some of its necessary traits.
## Example: if I wanted to create a page for myself in Wikipedia, I would create an article called Samson Y. Lai, and then write my biography and click Save. However, unless another Wikipedia article links to my article or vice versa, my article would essentially be {{Template:Viewer/Link|page=|url=https://en.wikipedia.org/wiki/Wikipedia:Orphan|label=orphaned}} and difficult to find except by explicit search. A person or bot editor would also later need to manually add Categories, such as "Person" and "Scientist" and "American", which can be difficult to assign or define after the fact.
## Conversely, in the Battery KB, to make a page which represents me, I go to the '''Category''' called "'''User'''" and create a new '''User Entity'''. This '''User Entity''' is an object that has pre-defined parameters, such as name, role, location, and relevant relationships to other '''Entities''' (e.g., '''Organization'''). In this way, the parameters are consistently used by all objects (no issues of "Person" vs. "Persons" vs. "person", etc.).
## This approach also applies to any other new '''Entity''': first find the '''Category''' that '''Entity''' would belong to, then create it using the +Create button and fill in the important parameters.
## For advanced users: some relationship parameters are pre-defined, but it is possible to add new parameters to a whole category. This should be done in consultation with those involved with curating the ontological infrastructure so as to be consistent and organized.
# ''Why have an ontological framework?''
## An ontological framework means that all of the information is both ''human-''readable and ''machine''-readable. This enables both humans and AIs/algorithms to sort and understand the data better by understanding what kind of data it is and how it is related to other data.
## Having an ontological framework also means that data isn't "loose" and lost as some uncategorized piece. Remember: '''everything''' is classified as a categorical entity with defined relationships to other objects, and ''nothing'' should exist outside of this framework.
## The design of Battery KB <u>forces</u> specific fields to link to an '''Entity''' instead of simply having a free-text field. This helps prevent data from existing outside of the ontological framework.
## Ontology and ontological frameworks have already been proven to be an effective method of sorting information and is already in use in search algorithms, such as by Google.


==== How to add a new entity on the fly: ====
==== How to add a new entity on the fly: ====
So you've created an entity or two under the pre-existing Categories. Great. But maybe you had some trouble putting in entities that don't exist yet because this wiki is in its early stages of creation. Let's say you want to add your organization and you found it doesn't exist in [[:Category:OSW1969007d5acf40539642877659a02c23]] yet.
So you've created an entity or two under the Categories. But, maybe you had some trouble putting in entities that don't exist yet because this wiki is in its early stages of creation. It can be a hassle to start creating a new '''Entity''', like a new '''User''', only to find that you want to link to other '''Entities''' that don't exist yet, like a new '''ResearchOrganization'''.


# First go to the Category and click + Create at the top.
# Go to [[:Category:OSW1969007d5acf40539642877659a02c23]] and find your organization.
# Fill in the usual information. Note that acronyms go under the field Short Name(s). But this parameter field doesn't show up by default.
# Let's say you want to type in the country of your organization in the '''Country''' field, but that specific '''Country''' doesn't exist as an '''Entity''' in Battery KB yet.
## Click at the top with "three bars select properties"
## Find the "Short name(s)" field and click the checkbox. Click outside of the small menu to close it.
## A new field box named "Short name(s):" is now in the Data-Editor window.
## Click on the + to create an entry in this parameter and type in the acronym/short name of the organization.
# Let's say you want to type in the country of your organization in the Country field, but the country doesn't exist as an entity in BatteryKB yet.
## The system won't let you type a country name that isn't an existing country entity. Remember: ''nothing'' exists outside of the ontological framework.
## The system won't let you type a country name that isn't an existing country entity. Remember: ''nothing'' exists outside of the ontological framework.
## But now that you know how to create an entity, you could go the Category for the Country and click + Create on it. However, there's a faster method.
## But now that you know how to create an entity, you could go the Category for the Country and click + Create on it. However, there's a faster method.
Line 140: Line 162:
## Now type in the Country field the name of the Country Entity you just created. It may take a moment to show up. Try typing slowly.
## Now type in the Country field the name of the Country Entity you just created. It may take a moment to show up. Try typing slowly.
# Click Save in the top right of the Data-editor window.
# Click Save in the top right of the Data-editor window.
# Finished!  
# Finished! Next step: improve the quality of your '''User Entity'''. Here is an example a good quality User Entity: [[Item:OSW72e733f317ef4cf9b8ca53e906c9acb9|Simon Clark]].  
 
==== How to be a good user: ====
 
# If you've never edited    Wikipedia before or worked on any other kind of wiki, reading the    introduction and basic five pillars of this page are extremely helpful to    understanding what a successful wiki culture requires: {{Template:Viewer/Link|page=|url=https://en.wikipedia.org/wiki/Wikipedia:A_primer_for_newcomers|label=https://en.wikipedia.org/wiki/Wikipedia:A_primer_for_newcomers}}.
# In essence, Wikipedia has    already developed processes and procedures that solve a lot of common    problems and the BatteryKB doesn't need to reinvent the wheel (at least,    completely).
# One of the best aspects about wikis in general is that you can learn nearly everything by simply copying what you see in a good page. However, this is more difficult in the BatteryKB due to how its ontological structuring.
# If you have worked on Wikipedia or another wiki, you will find that the BatteryKB operates differently. This is because the BatteryKB is built fundamentally on an ontological infrastructure. This means essentially that '''everything''' is classified as a categorical object with defined relationships to other objects, and ''nothing'' should exist outside of this framework.
# That means, compared to other wikis where you might simply create a page by writing on a blank slate and then link it to other places, you first instead go the category to which that object would belong and create it from there along with defining some of its necessary traits.
## Example: if I wanted to create a page for myself in Wikipedia, I would create an article called Samson Y. Lai, and then write my biography and click Save. However, unless another Wikipedia article links to my article or vice versa, my article would essentially be {{Template:Viewer/Link|page=|url=https://en.wikipedia.org/wiki/Wikipedia:Orphan|label=orphaned}} and difficult to find except by explicit search. A person or bot editor would also later need to manually add Categories, such as "Person" and "Scientist" and "American", which can be difficult to assign or define after the fact.
## Conversely, in the BatteryKB, to make a page or rather "entity/object" which represents me, I go the the pre-existing Category called "Users" and create a new User. This User object has pre-defined parameters, such as name, role, location, and relevant relationships to other objects (e.g., Institutional Affiliation). In this way, the parameters are consistently used by all objects (no issues of "Person" vs. "Persons" vs. "person", etc.) and thus, these parameters are usable and readable by machines. This also prevents orphan articles.
## This approach also applies to any other new entry: first find the category that object would belong to, then create it under that category and fill in the important parameters.
## For advanced users: some relationship parameters are pre-defined, but it is possible to add new parameters to a whole category. This should be done in consultation with those involved with curating the ontological infrastructure so as to be consistent and organized.


=== How to contribute to the wiki ===
=== How to contribute to the wiki ===
OK, now you should be set up with the basics of a user profile and understand the basic mechanics of how the BatteryKB is built. Now, you want to start making real contributions to the content. Here are some how-to guides for specific actions when creating wiki content.
OK, now you should be set up with the basics of a user account and understand the basic mechanics of how the Battery KB is built. Now, you want to start making real contributions to the content. Here are some how-to guides for specific actions when creating wiki content.


==== How to make a link: ====
==== How to make a link: ====
Line 168: Line 178:


==== How to add an image ====
==== How to add an image ====
First, before you attempt to add an image, you have to again understand that '''everything''' in this wiki exists on an ontological framework. Just as you can't type in a person's name into a parameter field as text without making them first a User entity, you can't simply upload an image to an article or entity as it is. The ''image'' has to exist as an '''entity''', too. But, as you also learned above, you can create this entity on the fly.
First, before you attempt to add an image, you have to again understand that '''everything''' in this wiki exists on an ontological framework. Just as you can't type in a person's name into a parameter field as text without making them first a '''User Entity''', you can't simply upload an image to an article or entity as it is. The ''image'' has to exist as an '''Entity''', too. But, as you also learned above, you can create this entity on the fly.


# At the top of the bar, click Insert Images and media.
# At the top of the bar, click Insert -> Insert Images and media.
# Under Media elements, click the + button to add a parameter field.
# Under Media elements, click the + button to add a parameter field.
# Click the blue button to "Create a new element in a separate dialog". This will allow you to upload the image as an ''entity'', save it and then come back to your original image insertion to ''link'' it to the article.
# Click the blue button to "Create a new element in a separate dialog". This will allow you to upload the image as a '''Wiki File Entity''', save it and then come back to your original image insertion to ''link'' it to the article.
# At the top of the new dialog box Data-Editor, it should say Wiki File.
# At the top of the new dialog box Data-Editor, it should say '''Wiki File'''.
## Add in filename
## Add in filename (this is required).
## If necessary, add in a description of the image. This can be thought of as the caption of the image (but it won't display as such automatically).
## Upload the image file in the File field or use Drag & Drop.
## Click Save in the upper right. This will return you to the '''Multimedia''' Data-Editor box.
## Your picture should now either be in the Search field. If not, try typing in the name you gave the image.
## A preview of the image should display.
## You can also add text into the Description field, which is displayed below the image element.
## If you want to use an image file which is already uploaded to the Battery KB, change Search from Attached File to Any File. The search field text will now search the entire Battery KB.
## When you're finished, click Save at the upper right to insert your image file.
## Click Save changes... in the top right of the page to finalize your edit to the '''Entity'''.
 
==== How to add a table: ====
 
# At the top of the visual editor, click Insert -> Table.
# A table will automatically be created. A pop-up helper window will allow you to delete the whole table or modify its properties.
# To modify an individual cell, double-click on the cell.
# To insert, move, or delete a column, left-click on the caret at the top of your column.
# To insert, move, or delete a row, left-click on the caret at the left of your row.
# The table will automatically adjust the width of its columns and height of its rows based on the amount of text contained in the cells.
#
 
==== How to start a new article: ====
 
==== How to help cultivate a good wiki culture: ====
# If you've never edited    Wikipedia before or worked on any other kind of wiki, reading the    introduction and basic five pillars of this page are extremely helpful to    understanding what a successful wiki culture requires: {{Template:Viewer/Link|page=|url=https://en.wikipedia.org/wiki/Wikipedia:A_primer_for_newcomers|label=https://en.wikipedia.org/wiki/Wikipedia:A_primer_for_newcomers}}.
# In essence, Wikipedia has    already developed processes and procedures that solve a lot of common    problems and the Battery KB doesn't need to reinvent the wheel (at least,    completely).


==== How to add a table ====
==== How to help with the organizational effort: ====


==== How to start a new article ====
# Presently, the Battery KB is in its early stages of creation and cannot rely on the organic type of growth that helps make Wikipedia a success. Instead, we need to have a targeted and coordinated effort.
# If you have learned something difficult, write a how-to guide to help others learn that skill.
# Contribute to developing a Manual of Style for the Battery KB.
# Get in touch with the administrators if you have advanced coding experience which can help with implementing the ontological framework.