Tutorials are lessons that take the reader by the hand through a series of steps to complete a project of some kind. They are what your project needs in order to show a beginner that they can achieve something with it. They are wholly learning-oriented , and specifically, they are oriented towards learning how rather than learning that. You are the teacher , and you are responsible for what the student will do. Under your instruction, the student will execute a series of actions to achieve some end.
The end and the actions are up to you, but deciding what they should be can be hard work. The end has to be meaningful , but also achievable for a complete beginner. The important thing is that having done the tutorial, the learner is in a position to make sense of the rest of the documentation, and the software itself.
Most software projects have really bad - or non-existent - tutorials. Tutorials are what will turn your learners into users. A bad or missing tutorial will prevent your project from acquiring new users. The best way of teaching is to have a teacher present, interacting with the student.
Tutorials need to be useful for the beginner, easy to follow, meaningful and extremely robust, and kept up-to-date. How to: Specific task descritpion. May be one step-by-step instructions to complete a task. Short descrition of each: Tutorial: Interactive set of instructions to teach by example in certaing area of knowladge. User Guide: A manual written by technical writer intended to give assistance to users. May include include screenshots and diagrams.
How to: Simplified and short description of how to accomplish some specific task meant to help non-experts. References: wiki:Tutorial A tutorial is one method of transferring knowledge and may be used as a part of a learning process.
Sign up or log in Sign up using Google. Sign up using Facebook. Sign up using Email and Password. Post as a guest Name. Email Required, but never shown.
Featured on Meta. Now live: A fully responsive profile. Linked 1. Basically, mock-ups are static images representing the final product design. A prototype is a mock-up that you can interact with: click some buttons, navigate between different pages, and so on.
A prototype can be created in a prototyping tool like Sketch or MockFlow. Using templates, UX designers can create interactive mock-ups on the early stages of development to be employed for usability testing.
A usability testing report is a short-form feedback document created to communicate the results of usability testing. The report should be as short as possible, with visual examples prevailing over text. Software architecture design documents, sometimes also called technical specifications, include the main architectural decisions made by the solution architect. Unlike the product requirement document mentioned above that describes what needs to be built, the architecture design documentation is about how to build it.
It has to describe in what way each product component will contribute to and meet the requirements, including solutions, strategies, and methods to achieve that. So, the software design document gives an overview of the product architecture, determines the full scope of work, and sets the milestones, thus, looping in all the team members involved and providing the overall guidance.
An effective design and architecture document comprises the following information sections:. Overview and background. Briefly describe the main goals of the project, what problems you are trying to solve, and the results you want to achieve. Underline the guiding architecture and design principles with which you will engineer the product. User Story description. Connect user stories with associated business processes and related scenarios.
You should try to avoid technical details in this section. Solution details. Describe the contemplated solution by listing planned services, modules, components, and their importance. Diagrammatic representation of the solution. Source: docs. That will help organize the work process and provide a clear metric to monitor progress.
A source code document is a technical section that explains how the code works. The main users of the source code documents are software engineers. Try to keep the document simple by making short sections for each element and supporting them with brief descriptions. There are different types of user acceptance testing in agile.
We have outlined the most common:. A quality management plan is an analog of a requirement document dedicated to testing.
This document sets the required standard for product quality and describes the methods to achieve this level. The plan helps to schedule QA tasks and manage testing activity for product managers, but, it is mainly used for large-scale projects. A test strategy is a document that describes the software testing approach to achieve testing objectives.
This document includes information about team structure and resource needs along with what should be prioritized during testing. A test strategy is usually static as the strategy is defined for the entire development scope. A test plan usually consists of one or two pages and describes what should be tested at a given moment. This document should contain:.
A test case specifications document is a set of detailed actions to verify each feature or functionality of a product. Usually, a QA team writes a separate specifications document for each product unit.
Test case specifications are based on the approach outlined in the test plan. A good practice is to simplify specifications description and avoid test case repetitions. Test checklist is a list of tests that should be run at a particular time. It represents what tests are completed and how many have failed. All points in the test checklists should be defined correctly. Try to group test points in the checklists. This approach will help you keep track of them during your work and not lose any.
If it helps testers to check the app correctly, you can add comments to your points on the list. This document should describe known problems with the system and their solutions. It also should represent the dependencies between different parts of the system.
Their documentation informs developers how to effectively use and connect to the required APIs. API documentation is a deliverable produced by technical writers as tutorials and guides. This type of documentation should also contain the list of all available APIs with specs for each one. As the name suggests, user documentation is created for product users.
However, their categories may also differ. So, you should structure user documentation according to the different user tasks and different levels of their experience. Generally, user documentation is aimed at two large categories:. The documentation created for end-users should explain in the simplest way possible how the software can help solve their problems.
Such user instructions can be provided in the printed form, online, or offline on a device. Here are the main types of the user documents:. The complete manual includes exhaustive information and instructions on how to install and operate the product. It lists the hardware and software requirements, detailed description of the features and full guidelines on how to get the most out of them, example inputs and outputs, possible tips and tricks, etc.
The troubleshooting guide gives end-users information on how to find and resolve possible issues that might arise when using the product.
For a detailed overview, check our article dedicated to user documentation. Some parts of user documentation, such as tutorials and onboarding, in many large customer-based products are replaced with onboarding training. Nevertheless, there are still complex systems remaining that require documented user guides.
User documentation requires technical writers to be more imaginative. Online end-user documentation may include the following sections:. Written in plain language with visual materials and step-by-step instructions included, user guides can become a powerful marketing tool and increase customer satisfaction and loyalty. Besides, to provide the best service for end-users, you should collect your customer feedback continuously. The wiki system is one of the more useful practices.
It helps to maintain the existing documentation. You can create your wiki pages using a wiki markup language and HTML code. Usually, administration docs cover installation and updates that help a system administrator with product maintenance.
Here are standard system administrators documents:. Process documentation covers all activities surrounding product development. You should have now something like this:.
You should have something like this now:. Press the Add Page button to add another page to the Documentation Tool. This time, we'll choose Goals Page from the drop-down menu. The Goals Page editor will now appear. Add the exact same content for Goals Page as in the Documentation Tool mentioned in the above example. After adding content to the Goals Page you should have something like this:. This time, we'll choose Standard Page from the drop-down menu.
The Standard Page editor will now appear. Add the exact same content for Standard Page as in the Documentation Tool mentioned in the above example. After adding content to the Standard Page you should have something like this:.
This time, we'll choose Goals Assessment Page from the drop-down menu. The Goals Assessment Page editor will now appear. Add the exact same content for Goals Assessment Page as in the Documentation Tool mentioned in the above example. After adding content to the Goals Assessment Page you should have something like this:. This time, we'll choose Document Export Page from the drop-down menu. The Document Export Page editor will now appear.
Add the exact same content for Document Export Page as in the Documentation Tool mentioned in the above example. After adding content to the Document Export Page you should have something like this:.
You should now have a similar result as the example on top of this page. Feel free to leave any comments or suggestions on how to improve this tutorial. I love how it helps guide the student in creating a document in a pre established format that the teacher has configured. Alas, I noticed the only way for the teacher to know his student has written in all the established blanks is for the student to export his document and I suppose email it or print it and show it to the professor. Is that possible?
Like it would be useful for the student to come back later on and respond other tabs he hasnt yet figured out. If there is any way the teacher can see what the student has worked on at any given moment throughout the course. H5P has everythign needed to support 1 the save content state features and 2 xAPI.
Won't be a big job to add this, but nobody has been willing to work on it or fund it yet. Would make the tool a lot better! Great tool! It would help users create Personal Learning Plans and export to Word.
But I'm afraid that it will frustrate them immensely and create a negative experience using H5P if they can't save their work and return to it later :. As mentioned in an earlier comment the H5P Core and several content types supports saving the user state, however getting it into Documentation Tool will require some developer work. I have added it as a feature request. Thanks for your quick response. This documentation tool seems useless to me as it is still not possible to save any goals and goals assesments.
Is there anyone working on this? Afaik, there is no one working on this at the moment. If you have programming skills, you are welcome to create a pull request! As a general study aid or tool for students, this should work well, from personal learning plans to project process reporting and learning diaries and seems flexible ennough to be adapted to different schools of process thought, such as aims and objectives rather than the goals concept ;-.
The state saving and other moderation capabilty features mentioned are indeed a very good idea to make this tool fully operational rather than just a more specific notepad tool. It would not be practical to have to recreate the specific process for each student or give them a guide document for creating it themselves.
An extension to this ideal functionality, is the facilitation of collaboration. Most project based learning activities involve more than one student, so the ability to cooperate, coordinate and collaborate on the project report writing is an important element. The tool button is provided within H5P at present. Once a process is created in the tool for a particular learning activity, can it be saved and resused from outside H5P, e.
This would allow us to use it as a general study tool and resource for students. The requirement to make it readable with comments by other students for peer review purposes.
I will mainly be using "standard page", with the text element. Using on Wordpress. I would love to add divs, tables or just paste in formatted code. Happy to hire out if you can point me at someone who knows how to do this. Be warned that any extra tags you add may break the rendering of the UI as not all content types are designed to hold any kind of HTML.
Using the documentation tool, some "sections" are longer than others.
0コメント