Editing Documentation:Rules and recommendations

Please, read this article before you contribute to the [https://timeline.oldera.org/timeline Timeline]. 

==Notability==
The rule of thumb (at least for now) is that if there is a Wikipedia article about the topic you want to create a layer about, then it is probably acceptable for this Timeline project. 

==Where to save your layers in the Library==
Use the folder ''Sandbox/Add your layers here''. The rest of the folders in the Library are protected from editing. The reason is that if someone messes up the Library structure, be it accidentally or on purpose, this will make entire app unusable for everybody until the problem is fixed. That’s why only admins are allowed to place layers in folders other than the one specified above. If everything is OK with your layer, some admin will eventually move it from the Sandbox to a more appropriate location.

==How data is organised in the Library (categorisation)==
Regular users can’t place layers anywhere other than the special folder already mentioned above. If you have a suggestion on where to put your layer, or maybe you have some general thoughts on how to organise data in the Library you can message me on [https://twitter.com/HTimelineApp Twitter] or [https://www.reddit.com/user/kgcoder Reddit]. Also, we will probably have a community on Reddit and/or there will be discussion pages on the this website. 

Basically, how to organise data in the Library is an open question. I’m not a historian, and even if I was, I wouldn’t want to impose my views on everybody. So there must be a way for everybody to have a say in this matter. 

However I have a guiding principle which I follow as I find it pretty sound. The principle is to avoid premature categorisation. This means grow any folder until it becomes unwieldy. Only then you subdivide it. If we do otherwise, putting categorisation first, creating a folder for every country in the world, for every possible topic, etc., we’d end up with a Library structure that has too many folders with too few layers in each of them. That would result in poor user experience, as users would spend a lot of time and clicks just to navigate this structure.

Another thing to remember is that although the Library structure looks like folders and files on your computer, folders and layers in the Library are just web pages that can be referenced from multiple folders. It means that there may be multiple ways to organise the same data. For example, you can categorise people by their profession, and in another part of the Library categorise the same people by country.

==Colors== 
Try to use only one color per layer. Only use multiple colours if it is absolutely necessary. The reason is that if two layers have multiple colours then when viewed together they visually merge together. 

Avoid black color or very dark colours that look like black. Black is used by the application as a ‘non-colour’ in cards that contain events from multiple layers. 

Avoid very light colours, because they are harder to distinguish on the white background.

==Naming layers and folders==
The titles of layers and folders you see in the Library are not necessarily the same as those that are used to name the corresponding data pages on the wiki. Page titles on the wiki should be as descriptive as possible. But in the Library the titles can be shorter. 

For example there is a layer that is stored on the wiki as ‘Periodization of Ancient Egypt’. But in the Library this same layer is named simply ‘Periodization’ since it is located inside ‘Ancient Egypt’ folder. 

If you are not an admin, you can only add your layer to the special folder and so you have to provide the name of the layer which is as descriptive as possible.

==Time intervals==
When working with lists of rulers try to avoid gaps if possible. Here is an example:

[[File:TimeIntervalWithGap.png]]

This is not very good, because we have a gap in the line of time intervals. Let’s look at instructions to find out how to fix it:
<blockquote><poem>
Time interval 1;;;;1705;1707;
Time interval 2;;;;1707;1708;
Time interval 3;;;;1707;1710;
Time interval 4;;;;1710;1711;
</poem></blockquote>

When the program reads the instructions, it places time intervals on the Timeline one by one, in order of their appearance in the list of instructions. It happens very quickly so it seems as though all the time intervals appear on the Timeline at the same moment. But in reality there is a process that looks like upside down Tetris, where each time interval tries to end up as high as possible.

So what happened in our example, is that ''Time interval 1'' was placed first as high as possible. Then ''Time interval 2'' was placed as high as possible. Then when it was time to place ''Time interval 3'' on the timeline, the space in the highest level was already occupied by ''Time interval 2'', so the third interval had to go lower. 

To fix it, you simply change the order of time intervals in the instructions, placing ''Time interval 3'' before ''Time interval 2''.

<blockquote><poem>
Time interval 1;;;;1705;1707;
Time interval 3;;;;1707;1710;
Time interval 2;;;;1707;1708;
Time interval 4;;;;1710;1711;
</poem></blockquote>

This is what you’ll get:

[[File:TimeIntervalWithoutGap.png]]

Looks much better.

==Sources==
In general, any Wikipedia article can be viewed as a legitimate source of information for the Timeline. Sometimes pages from other sites can be used. But you need to make sure that you have the right to copy data from those sites.

Every layer should have at least one source specified. All the information inside the layer must agree with layer’s sources. If there is an error in the source, don’t just fix it on the Timeline. If the source is Wikipedia page, fix that page first. If the source is some other site that you cannot edit and it contains an error, don’t use it. For every piece of information on the Timeline we should be able to say where it came from. 

If the events of the layer contain links to additional sources, you don’t have to specify those sources in the layer’s metadata. For example, let’s say there is an article on Wikipedia with a list of rulers of some country. And the list contains only years of reign of each ruler, but doesn’t provide specific dates. However, let’s say, you can find out specific dates if you open Wikipedia pages dedicated to each ruler. So you can use specific dates on the Timeline, and in the list of sources of your layer you only have to specify one Wikipedia article (the one containing the list of rulers without specific dates). All the other pages are one click away anyway, and so, if someone is curious where the specific dates come from, they can click on the ruler they are interested in and see those dates on Wikipedia.

==Conflicting sources==
Sometimes sources for different layers may conflict with each other. In general, if the sources are legit, we shouldn’t care if they conflict with each other or not. The Timeline of History is not about creating a single perfect version of history. It’s a place where you can put all the versions of history and compare them to each other. That is as long as those versions have something to back them up. We are not talking about pseudo scientific fantasies here. 

For example, we can use both middle chronology and short chronology to have two different versions of the same events in two different layers. 

[[File:MiddleVsShortChronology.png]]

Now we can visually compare them. And it’s totally fine. 

Here is another example:

[[File:QuintillusConflict.png]]

One layer says that Quintillus began his reign in April 270, while another layer says he died in April 270. If one of the sources has an error in it, then such error should be fixed. You can always fix errors on Wikipedia. However, if we genuinely don’t know when Quintillus died and the sources simply cite two different versions which come from two different books, and one version is not better then the other, then it’s OK to just show the conflicting versions of history on the Timeline.    

The fact that we can visualise the conflict of versions of history on the Timeline is actually a good thing.