Skip to content
This repository has been archived by the owner on Sep 24, 2022. It is now read-only.

Commit

Permalink
SVG images
Browse files Browse the repository at this point in the history
  • Loading branch information
Loquacity authored and Cameron Shorter committed Feb 28, 2021
1 parent 6b889e7 commit e8a453e
Show file tree
Hide file tree
Showing 12 changed files with 157,916 additions and 14 deletions.
74 changes: 62 additions & 12 deletions ia-guide/example.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,16 @@

# Information Architecture

**[[Let&#39;s Start-&gt;Intro]]**</tw-passagedata><tw-passagedata pid="2" name="Intro" tags="" position="225,100" size="100,100">Let&#39;s go on an adventure into another world.
**[[Let&#39;s Start-&gt;Intro]]**</tw-passagedata><tw-passagedata pid="2" name="Intro" tags="" position="225,100" size="100,100">config.footer.left: &quot;▰▱▱▱▱▱▱▱▱▱ 6%&quot;
--

Let&#39;s go on an adventure into another world.
This world is not entirely different to your own, but it might have some unexpected treasures - and pitfalls - for you to find.
It&#39;s an adventure into the mind of your reader.
They live in your world, but they don&#39;t always think like you.
And learning to think like a reader can be tricky!

{embed image: &#39;images/reader_world.png&#39;, alt: &#39;A blue and green globe sitting on top of a book with a red cover&#39;}
{embed image: &#39;images/reader_world.svg&#39;, alt: &#39;A blue and green globe sitting on top of a book with a red cover&#39;}

Have you ever been really good at something, and tried to show someone else how to do it?
It can be frustrating, because they just don&#39;t seem to get it, even though it seems easy and straight forward to you.
Expand All @@ -39,6 +42,7 @@
**[[Continue-&gt;Before you begin]]**

{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="3" name="Before you begin" tags="" position="350,100" size="100,100">userName: &#39;Type your name here&#39;
config.footer.left: &quot;▰▱▱▱▱▱▱▱ 12%&quot;
--

## Don&#39;t start yet!
Expand All @@ -48,6 +52,8 @@
This guide is designed to get you thinking about your readers in such a way that you&#39;ll end up knowing what docs you need to write.
It won&#39;t take very long for you to get through this guide, and it will save you time in the long run.

{embed image: &#39;images/stuck.svg&#39;, alt: &#39;A smiling person wearing a blue outfit is in a very big hole, with the words &quot;i am stuck&quot; in red&#39;}

By the end, you should have a good idea of who your main readers are, the kinds of things they are using your docs for, and what kinds of docs they might be expecting.
This will help you know which templates to use from the Good Docs Project, and give you the basics to start completing them.

Expand All @@ -60,7 +66,10 @@

and we can [[get started-&gt;What are you writing about]]

{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="4" name="What are you writing about" tags="" position="475,100" size="100,100">Hi {userName}! I&#39;m so glad you decided to join me!
{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="4" name="What are you writing about" tags="" position="475,100" size="100,100">config.footer.left: &quot;▰▱▱▱▱▱ 18%&quot;
--

Hi {userName}! I&#39;m so glad you decided to join me!

## What are you writing about?
The first thing we need to do is think about what you&#39;re writing about.
Expand All @@ -75,11 +84,15 @@
&gt; [[Car-&gt;Writing about a car]]
&gt; [[Nuclear Reactor-&gt;Writing about a nuclear reactor]]

{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="5" name="Writing about a toaster" tags="" position="600,100" size="100,100">## Writing about a toaster
{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="5" name="Writing about a toaster" tags="" position="600,100" size="100,100">config.footer.left: &quot;▰▰▱▱▱▱▱▱ 25%&quot;
--

## Writing about a toaster
Because the thing you are writing about is pretty simple and straightforward, you&#39;re probably thinking you don&#39;t need to spend much time writing docs.
Just because you might not need a lot of docs, you will still need something, though.
And working out what you need could be even more difficult, because you&#39;re going to need to think a little bit harder about who you&#39;re writing for.

{embed image: &#39;images/tooster.svg&#39;, alt: &#39;A silver toaster marked &quot;Super Tooster&quot; with a red discount star, and a sign saying &quot;wowzars!!!&quot;&#39;}

**Curse of Knowledge alert!!**
Just because your toaster seems super simple to you, doesn&#39;t mean everyone will find it as easy as you do.
Expand All @@ -91,11 +104,16 @@

Now, let&#39;s [[move on-&gt;Who are you writing for?]]

{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="6" name="Writing about a car" tags="" position="725,100" size="100,100">## Writing about a car
{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="6" name="Writing about a car" tags="" position="725,100" size="100,100">config.footer.left: &quot;▰▰▱▱▱▱▱▱ 25%&quot;
--

## Writing about a car
You lucky thing!
There is a pretty good chance that you needed to learn how to do this thing yourself, and hopefully it wasn&#39;t all that long ago, and you can fairly easily cast your mind back to those days when you didn&#39;t know what this thing was, or how it worked.
And if you didn&#39;t have to do this yourself, hopefully there is someone nearby who has, so go ask them questions!

{embed image: &#39;images/car.svg&#39;, alt: &#39;A cheering person in a green outfit driving a red and white striped sports car, with the caption &quot;big red car&quot;&#39;}

**Curse of Knowledge alert!!**
Try to remember that not everyone knows the same stuff, or learns in the same way.
What if your reader doesn&#39;t speak the same language, or is a new migrant from a place with a totally different culture?
Expand All @@ -106,7 +124,10 @@

Now, let&#39;s [[move on-&gt;Who are you writing for?]]

{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="7" name="Writing about a nuclear reactor" tags="" position="850,100" size="100,100">## Writing about a nuclear reactor
{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="7" name="Writing about a nuclear reactor" tags="" position="850,100" size="100,100">config.footer.left: &quot;▰▰▱▱▱▱▱▱ 25%&quot;
--

## Writing about a nuclear reactor
The first thing to work out if you are writing about a nuclear reactor is what reasonable assumptions can you make?
There&#39;s a fair chance that you can assume at least some kind of prior knowledge: a degree, some relevant experience, or perhaps using some other related tools or software.
When you have made these assumptions, write them down!
Expand All @@ -127,13 +148,16 @@
{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="8" name="Who are you writing for?" tags="" position="975,100" size="100,100">readerName1: &#39;Alex&#39;
readerName2: &#39;Bobbi&#39;
readerName3: &#39;Charlie&#39;
config.footer.left: &quot;▰▰▰▱▱▱▱▱▱▱ 30%&quot;
--

## Who are you writing for?
Now that we&#39;ve thought what you&#39;re writing about, let&#39;s consider who you&#39;re writing for.
It would be easy to think of just one person that you&#39;re writing for, but we need to remember that people come in all shapes and sizes.
So let&#39;s think up three different people, to try and make sure we&#39;re covering all the options.

{embed image: &#39;images/wave.svg&#39;, alt: &#39;A winking smiling person wearing a purple shirt and pants, with pastel coloured hair, waving&#39;}

The way you categorize your three readers is up to you, but sometimes the best way to start is by thinking of a beginner, an intermediate reader, and an expert.
Or, depending on the kind of product you have, you might think of an ordinary user, a system administrator, and a support person.

Expand All @@ -155,7 +179,10 @@

Let&#39;s take a closer look at our readers, and work out [[Why do they read the docs?]]

{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="9" name="Why do they read the docs?" tags="" position="1100,100" size="100,100">I&#39;m going to tell you a secret.
{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="9" name="Why do they read the docs?" tags="" position="1100,100" size="100,100">config.footer.left: &quot;▰▰▰▱▱▱▱▱▱ 36%&quot;
--

I&#39;m going to tell you a secret.

People don&#39;t read the docs because they&#39;re a great read.

Expand Down Expand Up @@ -186,6 +213,7 @@
{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="10" name="Reader One" tags="" position="1225,100" size="100,100">reader1action1: &#39;Install the product&#39;
reader1action2: &#39;Perform initial setup&#39;
reader1action3: &#39;Start their first project&#39;
config.footer.left: &quot;▰▰▰▰▱▱▱▱▱▱ 42%&quot;
--

To understand {readerName1}, let&#39;s start by thinking about how they might begin.
Expand All @@ -206,6 +234,7 @@
Or, if you&#39;re done, move on to [[Writing for your readers-&gt;Writing for your readers]]</tw-passagedata><tw-passagedata pid="11" name="Reader Two" tags="" position="100,225" size="100,100">reader2action1: &#39;Configure multiple users&#39;
reader2action2: &#39;Troubleshoot networking problems&#39;
reader2action3: &#39;Upgrade to a new version&#39;
config.footer.left: &quot;▰▰▰▰▰▱▱▱▱▱ 48%&quot;
--

To understand {readerName2}, let&#39;s start by thinking about how they might begin.
Expand All @@ -226,6 +255,7 @@
Or, if you&#39;re done, move on to [[Writing for your readers-&gt;Writing for your readers]]</tw-passagedata><tw-passagedata pid="12" name="Reader Three" tags="" position="225,225" size="100,100">reader3action1: &#39;Understand all the advanced features&#39;
reader3action2: &#39;Switch from hosted services to local&#39;
reader3action3: &#39;Shut down the reactor quickly during a meltdown&#39;
config.footer.left: &quot;▰▰▰▰▰▱▱▱▱▱ 54%&quot;
--

To understand {readerName3}, let&#39;s start by thinking about how they might begin.
Expand Down Expand Up @@ -279,6 +309,7 @@
reader3action1critscore: critpath19 + critpath20 + critpath21
reader3action2critscore: critpath22 + critpath23 + critpath24
reader3action3critscore: critpath25 + critpath26 + critpath27
config.footer.left: &quot;▰▰▰▰▰▰▱▱▱▱ 60% &quot;
--

## Writing for your readers
Expand Down Expand Up @@ -379,6 +410,7 @@
missingcontent7:&#39;Tuning Guide&#39;
missingcontent8:&#39;Administration Guide&#39;
missingcontent9:&#39;Reference Guide&#39;
config.footer.left: &quot;▰▰▰▰▰▱▱▱ 66%&quot;
--

## Identify the mess
Expand Down Expand Up @@ -421,7 +453,10 @@
So the very next step is to work out what we actually need, so we know we can cut some things from the list.
To do this, you need to [[State your intent-&gt;State your intent]]

{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="15" name="State your intent" tags="" position="600,225" size="100,100">## State your intent
{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="15" name="State your intent" tags="" position="600,225" size="100,100">config.footer.left: &quot;▰▰▰▰▰▰▰▱▱▱ 71%&quot;
--

## State your intent

If you wanted to build a house, you wouldn&#39;t start laying bricks until you&#39;d had a think about what kind of house you want to build.
How big is it going to be?
Expand All @@ -435,7 +470,10 @@

When you&#39;ve considered these things, and determined the kind of documentation you want to make sure your project has, you&#39;re just about ready to [[Face reality-&gt;Face reality]]

{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="16" name="Face reality" tags="" position="725,225" size="100,100">## Face reality
{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="16" name="Face reality" tags="" position="725,225" size="100,100">config.footer.left: &quot;▰▰▰▰▰▰▰▱▱ 78%&quot;
--

## Face reality
By now, you should have a good idea of what your ideal documentation would look like.
It would be wonderful!
A shining beacon of docs goodness, hitting all the critical paths for all your readers, and people will talk about it for years to come!
Expand All @@ -453,6 +491,7 @@
Make sure you&#39;re not biting off more than you can chew, and [[Choose a direction-&gt;Choose a direction]]

{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="17" name="Choose a direction" tags="" position="850,225" size="100,100">missingcontent10: &#39;Anything else?&#39;
config.footer.left: &quot;▰▰▰▰▰▰▰▰▱▱ 83%&quot;
--

## Choose a direction
Expand All @@ -477,7 +516,10 @@
Now you get to decide how to move forward.
That starts with [[Measuring the distance-&gt;Measure the distance]]

{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="18" name="Measure the distance" tags="" position="975,225" size="100,100">## Measure the distance
{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="18" name="Measure the distance" tags="" position="975,225" size="100,100">config.footer.left: &quot;▰▰▰▰▰▰▰▰▰▱ 90%&quot;
--

## Measure the distance
Don&#39;t let your docs project be like your New Year resolutions, forgotten and lonely by the end of the year.
The best way to make sure you stick to your docs goals, is to work out how much you can do, and set a deadline for each step in the process.

Expand All @@ -503,7 +545,10 @@

There&#39;s just one more thing you need to do: [[Prepare to adjust-&gt;Prepare to adjust]]

{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="19" name="Prepare to adjust" tags="" position="1100,225" size="100,100">## Prepare to adjust
{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="19" name="Prepare to adjust" tags="" position="1100,225" size="100,100">config.footer.left: &quot;▰▰▰▰▰▰▰▰▰▱ 99%&quot;
--

## Prepare to adjust

Finally, the most important thing you need to do is to be flexible.
Things don&#39;t always work out, and that&#39;s OK!
Expand Down Expand Up @@ -539,7 +584,10 @@

Or, if you want to keep reading, you can [[Find out more about information architecture-&gt;Further reading]]

{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="20" name="Further reading" tags="" position="1225,225" size="100,100">## Further Reading
{back link, label: &#39;Or go back a step&#39;}</tw-passagedata><tw-passagedata pid="20" name="Further reading" tags="" position="1225,225" size="100,100">config.footer.left: &quot;▰▰▰▰▰▰▰▰▰▰ 100%&quot;
--

## Further Reading

This document was largely based on the brilliant book by Abby Covert called [[How to Make Sense of Any Mess-&gt;http://www.howtomakesenseofanymess.com/]].
It&#39;s a quick read, and it doesn&#39;t just apply to technical documentation, you can use the principles in that book to help you organize anything at all.
Expand All @@ -548,6 +596,8 @@
It has everything you need to know, including answers to questions you didn&#39;t know you needed to ask.
It has a polar bear on the cover.

{embed image: &#39;images/banana.svg&#39;, alt: &#39;A reclining smiling banana with red writing saying &quot;lets go banana&quot;&#39;}

## That&#39;s it!

You&#39;ve reached the end of the interactive Information Architecture Guide.
Expand Down
11 changes: 9 additions & 2 deletions ia-guide/ia-cyoa.tw
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ It's an adventure into the mind of your reader.
They live in your world, but they don't always think like you.
And learning to think like a reader can be tricky!

{embed image: 'images/reader_world.png', alt: 'A blue and green globe sitting on top of a book with a red cover'}
{embed image: 'images/reader_world.svg', alt: 'A blue and green globe sitting on top of a book with a red cover'}

Have you ever been really good at something, and tried to show someone else how to do it?
It can be frustrating, because they just don't seem to get it, even though it seems easy and straight forward to you.
Expand Down Expand Up @@ -66,7 +66,7 @@ When you're excited about a new project, it's super-tempting to just start writi
This guide is designed to get you thinking about your readers in such a way that you'll end up knowing what docs you need to write.
It won't take very long for you to get through this guide, and it will save you time in the long run.

{embed image: 'images/stuck.png', alt: 'A smiling person wearing a blue outfit is in a very big hole, with the words "i am stuck" in red'}
{embed image: 'images/stuck.svg', alt: 'A smiling person wearing a blue outfit is in a very big hole, with the words "i am stuck" in red'}

By the end, you should have a good idea of who your main readers are, the kinds of things they are using your docs for, and what kinds of docs they might be expecting.
This will help you know which templates to use from the Good Docs Project, and give you the basics to start completing them.
Expand Down Expand Up @@ -114,6 +114,7 @@ Because the thing you are writing about is pretty simple and straightforward, yo
Just because you might not need a lot of docs, you will still need something, though.
And working out what you need could be even more difficult, because you're going to need to think a little bit harder about who you're writing for.

{embed image: 'images/tooster.svg', alt: 'A silver toaster marked "Super Tooster" with a red discount star, and a sign saying "wowzars!!!"'}

**Curse of Knowledge alert!!**
Just because your toaster seems super simple to you, doesn't mean everyone will find it as easy as you do.
Expand All @@ -137,6 +138,8 @@ You lucky thing!
There is a pretty good chance that you needed to learn how to do this thing yourself, and hopefully it wasn't all that long ago, and you can fairly easily cast your mind back to those days when you didn't know what this thing was, or how it worked.
And if you didn't have to do this yourself, hopefully there is someone nearby who has, so go ask them questions!

{embed image: 'images/car.svg', alt: 'A cheering person in a green outfit driving a red and white striped sports car, with the caption "big red car"'}

**Curse of Knowledge alert!!**
Try to remember that not everyone knows the same stuff, or learns in the same way.
What if your reader doesn't speak the same language, or is a new migrant from a place with a totally different culture?
Expand Down Expand Up @@ -188,6 +191,8 @@ Now that we've thought what you're writing about, let's consider who you're writ
It would be easy to think of just one person that you're writing for, but we need to remember that people come in all shapes and sizes.
So let's think up three different people, to try and make sure we're covering all the options.

{embed image: 'images/wave.svg', alt: 'A winking smiling person wearing a purple shirt and pants, with pastel coloured hair, waving'}

The way you categorize your three readers is up to you, but sometimes the best way to start is by thinking of a beginner, an intermediate reader, and an expert.
Or, depending on the kind of product you have, you might think of an ordinary user, a system administrator, and a support person.

Expand Down Expand Up @@ -675,6 +680,8 @@ If you really want to delve into information architecture for technical document
It has everything you need to know, including answers to questions you didn't know you needed to ask.
It has a polar bear on the cover.

{embed image: 'images/banana.svg', alt: 'A reclining smiling banana with red writing saying "lets go banana"'}

## That's it!

You've reached the end of the interactive Information Architecture Guide.
Expand Down
Loading

0 comments on commit e8a453e

Please sign in to comment.