- View, Edit & History
- Guide Steps
- Adding a Title
- Adding and Editing Steps
- Keyboard Shortcuts
Guides allow you to easily illustrate technical procedures to any audience. Dozuki guides are used for everything from replacing the logic board on an iPad Mini to calibrating a CNC machine. This overview will help you understand the various elements that make up a guide page.
View, Edit & History ¶
Each guide page features three tabs in the top right corner of the page: View, Edit & History.
This tab shows the guide in its viewing format. This format is how all site users will view and interact with the guide.
This tab is where you add and edit the elements of your guide page that will appear when viewing the guide under the View tab. Guide editing is organized under three sub-sections: Introduction, Details and Guide Steps.
This tab is where you can view the entire revision history for a guide page, organized by date and time, as well as by Release Version (if your site has the Version Control Feature activated).
The Guide Introduction is the first tab available when creating and editing a guide. The Introduction is where you can add introductory information for the guide, including the guide summary and guide flags, to help your users become better acquainted with your procedure.
Guide Type ¶
|Note: This option will only be available if you have more than one Guide Type activated on your site. Site admins can activate the following "guide types": How-To (default), Replacement, Installation, Repair, Disassembly, Maintenance and Troubleshooting.|
If applicable, your site administrator can choose to allow guide types for the various procedures on your site. Click on the drop-down menu at the top of the Introduction tab to select a type from your site's available options.
Each guide type is organized within its own section on the Category Page. Here is an example of a category with guides of three different types:
Category Name ¶
Use the Category Name field to choose which category this guide will display in. For example, if you are showing people how to add a hand brake to a Razor scooter, your category would likely be "Razor Scooter".
In the summary field, use a sentence or two to briefly describe your guide. What you type here will show up as a quick blurb in search results—so it's important to be succinct.
Example Summary: Constructing your own suit of chain mail armor from ordinary household objects.
Provide a basic outline of your guide in the introduction field. Advice, anecdotes, and important safety protocols all belong here. The introduction may be as brief or as lengthy as you wish.
Flags tell the user about the status of a guide. A detailed discussion on the specifics of guide flags can be found on the About Flags Help Page. By default, the “In Progress” flag is added to any new guide. You may add or remove most flags by returning to the Guide Introduction tab at any point. Some flags, such as “User Contributed,” can only be removed by an administrator.
To ensure quality in all guides, any member can flag another member’s guide for any number of reasons. Some of these reasons include incorrect grammar, off-topic material, offensive text, or low-quality images. Flags are intended to point out opportunities for continuous improvement.
Access Control ¶
Okay, so you've created a guide. Now it's time to control who has access to it. Guide Access Control on a Dozuki site is very flexible and can help your end users find the procedures they need quickly and easily. When you have your guide set to Public, it is viewable to every user on the site once it is published. If a guide is set to Private, it is only viewable by your privileged users (Admins and Authors) unless otherwise specified. To make exceptions to the privacy settings, simply type in the name of the team or individual in the specified areas, select from the drop-down menu that appears, and hit save. Once published, those specific users or teams will now have access to that content, no matter their user type.
Edit Permissions ¶
Edit Permissions is an administrator–only feature that keeps track of edits made by site members. Set the permissions threshold from 0 to ∞ for any guide by adjusting the slider on the right side of your screen while editing the guide. Edits made to a guide by a user with a reputation lower than the permission threshold will be sent to the patrol queue for approval.
To learn more about editing permissions, see our page about the Permissions Manager.
What's the point of making a guide if no one will see it? Tags help your guide to show up in more search results. Simply add pertinent tags one-by-one, and then save them. Anyone may add, delete, or edit tags on a guide at any point.
Delete Guide ¶
Deleting a guide is an irreversible leap of faith that can only be made by a guide's creator or an administrator. Once a guide is deleted, it cannot be recovered. The "Delete Guide" button is located at the bottom left of the page while editing (adjacent to the “Undo”, “Preview”, and “Save” buttons). Before clicking "Delete Guide," consider repurposing or improving the guide. Deleting a guide cannot be undone, even by reverting to a previous version in the guide history.
Guide Details give a user the information they need before starting a procedure. Required tools and parts, prerequisites, time required, and many other logistics-related pieces of information go here.
Time Required ¶
Give people who follow your guide an estimate of how long this project will take. It's a good idea to be a little conservative with this estimate. It might take you less time to finish a project than it would someone who is attempting the task for the first time.
Some procedures are fairly simple for any user—and others require years of specialized experience. Select a level of difficulty from the drop-down menu so you can give users an idea of how easy or hard the task will be.
Prerequisite Guides ¶
Each guide is a completely independent step-by-step tutorial, but that doesn't mean that similar steps aren't involved. If several guides follow some of the same procedures, you won't have to duplicate your work. Use Prerequisite Guides, a feature where you can include one guide within another, to streamline your guide creation process.
Here's an iFixit guide for removing a MacBook battery. The battery removal guide is a prerequisite for the MacBook RAM guide. You can see that the first two steps of the MacBook RAM guide are actually the steps for removing the battery.
Note: New steps cannot be created in between prerequisite guides. New steps can only be added after every prerequisite guide.
Using prerequisites can save you a lot of time, but there are potential pitfalls. You can only use prerequisites for portions of the disassembly that are sequential. Basically, you cannot insert new content between prerequisite guides, it can only be added after.
Advanced Prerequisites ¶
If a guide you want to use as a prerequisite does not belong in the same category as the guide you are writing, you can use wiki syntax to add it as a prerequisite. Simply locate the guide ID in the URL of the guide you would like to add as a prerequisite (Hint: the guide ID is the last number in the guide URL). Now enter the the following wiki syntax directly into the prerequisite field: guideid:77. In this example the number 77 is the guide ID.
Any item or instrument that is required or recommended to perform your specific procedure constitutes a tool. Tools may be conventional (screwdriver, pliers, hammer, hacksaw, etc.), not-so-conventional (sickle, leather belt, kitchen utensil, etc.), or highly specialized (piston ring compressor, bicycle chain remover, tri-wing screwdriver, etc.). An easy way to determine if an item is a tool is to ask yourself, "Will I still have this item after this procedure?" If this answer is yes, then you've likely got a tool.
To add tools to your guide, click "Add a Tool" and begin typing the name of the tool. You'll see a drop-down menu with a list of suggested tools to select. If the tool you want to add is not on that list, create a new tool to add to the guide.
Provide a brief explanation of the tool that explains how and what it's used for. If it is an especially hard-to-find tool, you might want to provide a link to a site where the tool can be purchased.
After adding your tools, you may select "Edit Details" for each of the tools to add a type, change the quantity, or include notes. For a hacksaw, you may want to specify the number of teeth per inch, and in the note explain that cutting through metal requires more teeth per inch than a softer material like wood. You can go back and edit these details at any time by clicking the pencil icon next to the tool name on Guide Details.
Tools do not automatically import from prerequisite guides. Use the "Import Tools from Prerequisite Guides" feature to add the tools from all of your prerequisite guides to your current guide.
Whether you're building, fixing, or modifying something, chances are that the procedure is going to require parts of some sort. Parts—like tools—are important to completing the guide, but are often what makes the guide necessary. If you had no speakers or lights to install in your boom box, then there would be no need for a guide showing how to install them. Whereas tools are the items that you will still have after following the guide, parts are items that you probably will no longer have afterwards. Specific components, mechanical fasteners, adhesives, and lubricants are all parts.
To add parts to your guide, simply click the "Add a part" button and begin typing the name of the part you are adding. You'll see a drop-down menu with a list of suggested parts. If the part you want to add is not on that list, you have the option to create a new part.
Provide a brief explanation of the part that describes what it does and where it goes. If it is an especially hard-to-find part, you might want to provide a link to a site that sells it.
After adding your parts, you may select "Edit Details" for each of the parts to add a type, change the quantity, or include notes. For example, if your part is a quart of 5W-30 automotive engine oil, the type would be conventional or synthetic, the quantity might be 5, and in the notes you could tell others that 10W-30 is also an acceptable oil to use in warmer climates. You can go back and edit these details at any time by clicking the pencil icon next to the part name on optional details.
Add a note to the end of your guide in the Conclusion. This can be a simple congratulatory statement, like "You did it!" or informational, like "To reassemble your refrigerator, follow these directions in reverse order." If you've said all you have to say, just leave this section blank.
Attach Documents ¶
Some procedures require additional documents, such as wiring diagrams or manufacturer's manuals. Add these documents by opening the "Documents" tab at the bottom of the Guide Details. Click the "Upload" button and select the documents you wish to add to the guide. Only PDFs can be attached to guides. After uploading the documents, attach them to the guide by dragging them to the indicated area.
Bulk Step Creator Tool ¶
Just because you have written a great how-to guide outside of our Guide Creator doesn't mean that you have to start over on all that hard work. The Bulk Step Creator Tool allows you to paste text from a webpage or text document and convert it directly to guide steps.
Begin adding steps by clicking "Bulk-Import Steps" in the "Details" tab. The first line of each step can specify a site's title. To add a title to your step, type in "Title:" and then the desired step title. If you would rather not give your step a title, just start adding bullets. To add bullets, enter one line of text for each bullet within a step. There should not be an empty line between bullets within the same step. To add a new step, put an empty line between the last line of the previous step and the first line or title of the new step. When you have added all of your steps, click "Create Steps" and your steps will appear.
The Bulk Step Creator tool will take this:
And turn it into this:
Permissions Manager ¶
Permissions Manager is an administrator–only feature that keeps track of edits made by site members. Set the permissions threshold to any number from 0 to ∞ for any guide by adjusting the slider to the right of the text window. Edits made to a guide by a user with a reputation lower than the permission threshold will be sent to the patrol queue for approval.
For more information, see our Permissions Manager page.
What's the point of making a step-by-step how-to guide if no one will see it? Add pertinent tags to your guide and it will show up in more search results. Simply add the tags one-by-one, and then save them. Anyone may add, delete, or edit tags on a guide at any point.
Guide Steps ¶
Learn how to add text and photos, and edit bullets to make your step-by-step guide a complete documentation experience.
Images are an incredibly important aspect of a guide that will set your documentation apart from others out there. Use the Media Manager to add the desired image(s) to each step. Each step may have up to three images.
Adding a Title ¶
The "Add a Title" field allows you to give each step a unique title. Choose a title that will help users understand what will be explained to them in this step. This field is located directly above the images when editing a step. Simply click on "Add a Title" and type in the desired step title.
Guide bullets are customizable icons that make your steps easy to follow. By default the bullets in a guide will appear black, but you can change their color or shape by clicking on them while editing a guide step.
Colored Bullets ¶
If you have added any markers to an image, and a particular bullet corresponds to a marker on the image, change the bullet color to match that marker.
Caution, Note, and Reminder Bullets ¶
In addition to colored bullets, there are also special icon bullets—each with its own purpose.
- Use a caution bullet whenever someone attempting the procedure may injure themselves or damage their equipment.
- Note bullets are useful bits of information that complement the instructions.
- The reminder bullet is used to provide information for after the procedure is completed, such as tips for reassembly.
View our step by step guide that explains how to format and use bullet points within a guide step.
Adding and Editing Steps ¶
Steps are the building blocks for a solid set of documentation. The Guide Creator makes adding and editing steps easy and efficient.
Adding Guide Steps ¶
There are two ways to add a new step to a guide.
To add a step to the end of a guide, click the "+ Add Step" button on the right side of the Guide Creator.
To add a step immediately after the one you are currently working on, click "+ Insert Step" under the bullets in the Guide Creator.
Editing Guide Steps ¶
To edit a Guide Step, click the "Edit" button at the top right corner of the guide. This will direct you to the Guide Introduction edit page. From the list of guide steps on the right side of the page, select the step you wish to edit. You can also edit a specific step by viewing a guide and selecting "Edit" to the right of the step title.
Simply click the text for the particular bullet that you would like to edit, and type in the information you wish to add. Once you are done editing a step, click "Save" to save your changes.
Edit Step Icons ¶
When editing a bullet on a Guide Step, you'll see four icons below the bullet you are editing: a left arrow, a right arrow, a plus sign, and an X. The arrows shift a bullet left or right, allowing you to indent certain lines; the plus sign adds a bullet below the one you're working on; and the X deletes the bullet you are working on. You cannot delete the only line of a guide step. Instead, you must select "delete step."
Deleting Guide Steps ¶
To delete a guide step, edit that step and select the "Delete Step" button in the lower left corner.
Rearranging Guide Steps ¶
From any page in the Guide Creator, click "Rearrange Steps" above the list of steps in the guide. Then click-hold and drag the thumbnail of the step you would like to move to where you want it to be, and click "Save".
Keyboard Shortcuts ¶
You're a busy person. You know what's great for that? Shortcuts. Instead of clicking all those buttons, save time by using these keyboard shortcuts while editing a guide step. All shortcuts can use 'ctrl' or 'alt' interchangeably:
- escape: Stop editing the current bullet
- ctrl+n: Stop editing the current bullet and move to the next one
- ctrl+p: Stop editing the current bullet and move to the previous one
- ctrl+shift+n: Stop editing the current bullet and insert and move to new line below
- ctrl+shift+p: Stop editing the current bullet and insert and move to new line above
- tab: Indent current bullet
- shift + tab: Dedent current bullet
- ctrl+d: Delete current bullet
- Hit Enter to move to the next line, or create a new line if you're at the bottom
- If you hit enter while on an unmodified, fresh line, it'll be removed.
- So, if you're on the last line, you can hit enter twice to stop editing.
- shift-enter: Will behave like enter, but in reverse (going up the list of lines).
When viewing a guide:
- J: Jump to the next step
- K: Jump to the previous step