diff --git a/docs/src/makielayout/axis.md b/docs/src/makielayout/axis.md
index 1d997eca1..7149b840c 100755
--- a/docs/src/makielayout/axis.md
+++ b/docs/src/makielayout/axis.md
@@ -13,33 +13,31 @@ Here's how you create one
 ```@example laxis
 using CairoMakie
 
-scene, layout = layoutscene(resolution = (1200, 900))
+f = Figure(resolution = (1200, 900))
 
-ax = layout[1, 1] = Axis(scene, xlabel = "x label", ylabel = "y label",
+ax = Axis(f[1, 1], xlabel = "x label", ylabel = "y label",
     title = "Title")
 
-scene
+f
 ```
 
 
-## Plotting Into an Axis
+## Plotting into an Axis
 
 You can use all the normal mutating 2D plotting functions with an `Axis`.
-The only difference is, that they return the created plot object and not
-the axis (like Makie's base functions return the `Scene`). This is so
-that it is more convenient to save and manipulate the plot objects.
+These functions return the created plot object.
+Omitting the `ax` argument plots into the `current_axis()`, which is usually the axis that was last created.
 
 
 ```@example laxis
 lineobject = lines!(ax, 0..10, sin, color = :red)
+scatobject = scatter!(0:0.5:10, cos, color = :orange)
 
-scene
+f
 ```
 
-![basic axis plotting](basic_axis_plotting.svg)
-
 
-## Setting Axis Limits and Reversing Axes
+## Setting Axis limits and reversing axes
 
 You can set axis limits with the functions `xlims!`, `ylims!` or `limits!`. The
 numbers are meant in the order left right for `xlims!`, and bottom top for `ylims!`.
@@ -94,7 +92,7 @@ lines(f[1, 2], 0..10, sin, axis = (limits = (0, 10, -1, 1),))
 f
 ```
 
-## Modifying Ticks
+## Modifying ticks
 
 To control ticks, you can set the axis attributes `xticks/yticks` and `xtickformat/ytickformat`.
 
@@ -119,7 +117,7 @@ As a third option you can pass a function taking minimum and maximum axis value
 For formatting, you can pass a function which takes a vector of numbers and outputs a vector of strings.
 You can also pass a format string which is passed to `Formatting.format` from [Formatting.jl](https://github.com/JuliaIO/Formatting.jl), where you can mix the formatted numbers with other text like in `"{:.2f}ms"`.
 
-### Predefined Ticks
+### Predefined ticks
 
 The default tick type is `LinearTicks(n)`, where `n` is the target number of ticks which the algorithm tries to return.
 
@@ -174,7 +172,7 @@ axes[4].xlabel = "Time"
 scene
 ```
 
-## Minor Ticks and Grids
+## Minor ticks and grids
 
 You can show minor ticks and grids by setting `x/yminorticksvisible = true` and `x/yminorgridvisible = true` which are off by default.
 You can set size, color, width, align etc. like for the normal ticks, but there are no labels.
@@ -208,7 +206,7 @@ fig
 ```
 
 
-## Hiding Axis Spines and Decorations
+## Hiding Axis spines and decorations
 
 You can hide all axis elements manually, by setting their specific visibility attributes to `false`, like
 `xticklabelsvisible`, but that can be tedious. There are a couple of convenience functions for this.
@@ -218,15 +216,15 @@ To hide spines, you can use `hidespines!`.
 ```@example
 using CairoMakie
 
-scene, layout = layoutscene(resolution = (1200, 900))
+f = Figure(resolution = (1200, 900))
 
-ax1 = layout[1, 1] = Axis(scene, title = "Axis 1")
-ax2 = layout[1, 2] = Axis(scene, title = "Axis 2")
+ax1 = Axis(f[1, 1], title = "Axis 1")
+ax2 = Axis(f[1, 2], title = "Axis 2")
 
 hidespines!(ax1)
 hidespines!(ax2, :t, :r) # only top and right
 
-scene
+f
 ```
 
 
@@ -235,7 +233,23 @@ When hiding, you can set `label = false`, `ticklabels = false`, `ticks = false`,
 arguments if you want to keep those elements.
 It's common, e.g., to hide everything but the grid lines in facet plots.
 
-## Controlling Axis Aspect Ratios
+```@example
+using CairoMakie
+
+f = Figure(resolution = (1200, 700))
+
+ax1 = Axis(f[1, 1], title = "Axis 1")
+ax2 = Axis(f[1, 2], title = "Axis 2")
+ax3 = Axis(f[1, 3], title = "Axis 3")
+
+hidedecorations!(ax1)
+hidexdecorations!(ax2, grid = false)
+hideydecorations!(ax3, ticks = false)
+
+f
+```
+
+## Controlling Axis aspect ratios
 
 If you're plotting images, you might want to force a specific aspect ratio
 of an axis, so that the images are not stretched. The default is that an axis
@@ -255,11 +269,10 @@ using FileIO
 using Random # hide
 Random.seed!(1) # hide
 
-scene, layout = layoutscene(resolution = (1200, 900))
+f = Figure(resolution = (1200, 900))
 
-axes = [Axis(scene) for i in 1:2, j in 1:3]
+axes = [Axis(f[i, j]) for i in 1:2, j in 1:3]
 tightlimits!.(axes)
-layout[1:2, 1:3] = axes
 
 img = rotr90(load("../assets/cow.png"))
 
@@ -284,11 +297,11 @@ axes[2, 2].aspect = AxisAspect(2)
 axes[2, 3].title = "AxisAspect(0.5)"
 axes[2, 3].aspect = AxisAspect(0.5)
 
-scene
+f
 ```
 
 
-## Controlling Data Aspect Ratios
+## Controlling data aspect ratios
 
 If you want the content of an axis to adhere to a certain data aspect ratio, there is
 another way than forcing the aspect ratio of the whole axis to be the same, and
@@ -370,30 +383,77 @@ separately.
 ```@example
 using CairoMakie
 
-scene, layout = layoutscene(resolution = (1200, 900))
+f = Figure(resolution = (1200, 900))
+
+ax1 = Axis(f[1, 1])
+ax2 = Axis(f[1, 2])
+ax3 = Axis(f[2, 2])
 
-layout[1, 1:3] = axs = [Axis(scene) for i in 1:3]
-linkxaxes!(axs[1:2]...)
-linkyaxes!(axs[2:3]...)
+linkyaxes!(ax1, ax2)
+linkxaxes!(ax2, ax3)
 
-axs[1].title = "x linked"
-axs[2].title = "x & y linked"
-axs[3].title = "y linked"
+ax1.title = "y linked"
+ax2.title = "x & y linked"
+ax3.title = "x linked"
 
-for i in 1:3
-    lines!(axs[i], 1:10, 1:10, color = "green")
+for (i, ax) in enumerate([ax1, ax2, ax3])
+    lines!(ax, 1:10, 1:10, color = "green")
     if i != 1
-        lines!(axs[i], 1:10, 11:20, color = "blue")
+        lines!(ax, 11:20, 1:10, color = "red")
     end
     if i != 3
-        lines!(axs[i], 11:20, 1:10, color = "red")
+        lines!(ax, 1:10, 11:20, color = "blue")
     end
 end
 
-scene
+f
+```
+
+
+## Changing x and y axis position
+
+By default, the x axis is at the bottom, and the y axis at the left side.
+You can change this with the attributes `xaxisposition = :top` and `yaxisposition = :right`.
+
+```@example
+using CairoMakie
+
+f = Figure(resolution = (800, 800))
+
+for i in 1:2, j in 1:2
+    Axis(
+        f[i, j],
+        limits = (0, 5, 0, 5),
+        xaxisposition = (i == 1 ? :top : :bottom),
+        yaxisposition = (j == 1 ? :left : :right))
+end
+
+f
 ```
 
 
+## Creating a twin axis
+
+There is currently no dedicated function to do this, but you can simply add an Axis on top of another, then hide everything but the second axis.
+
+Here's an example how to do this with a second y axis on the right.
+
+```@example
+using CairoMakie
+
+f = Figure(resolution = (800, 600))
+
+ax1 = Axis(f[1, 1], yticklabelcolor = :blue)
+ax2 = Axis(f[1, 1], yticklabelcolor = :red, yaxisposition = :right)
+hidespines!(ax2)
+hidexdecorations!(ax2)
+
+lines!(ax1, 0..10, sin, color = :blue)
+lines!(ax2, 0..10, x -> 100 * cos(x), color = :red)
+
+f
+```
+
 ## Axis interaction
 
 An Axis has a couple of predefined interactions enabled.
diff --git a/src/makielayout/layoutables/axis.jl b/src/makielayout/layoutables/axis.jl
index 675e5b169..f3922cbce 100644
--- a/src/makielayout/layoutables/axis.jl
+++ b/src/makielayout/layoutables/axis.jl
@@ -133,7 +133,7 @@ function layoutable(::Type{<:Axis}, fig_or_scene::Union{Figure, Scene}; bbox = n
         elseif yaxisposition == :right
             rightline(FRect2D(area))
         else
-            error("Invalid xaxisposition $xaxisposition")
+            error("Invalid yaxisposition $yaxisposition")
         end
     end