Software design documentation wiki

As you can see, documentation isn't just putting a bunch of instructions and words together. There's a method to the madness, friends. Remember these guiding principles before, during, while you sleep, and after creating your documentation:. Your documentation should have just the right amount of information to get the job done without raising a help ticket.

Provide key points and the option for readers to go into further detail. Visuals are key to comprehension. Product design, code samples, in-product demos, screenshots, and video tutorials play a large role in helping a reader to fully understand the concept, the how-to, or the to-do.

Also keep in mind the layout, legibility, and easily digestible chunks. Take a walk in the user's shoes. Know your reader, take a stroll through their user journey of your product and your documentation.

This should always guide how and what you write. The best documentation is clear, concise, informative, and most importantly, adds value for its audience.

Explore team collaboration software like Confluence for your documentation, and spend less time hunting things down, and more time making things happen. Close View this page in your language? All languages Choose your language. Open and close the navigation menu. Features Templates Enterprise Pricing. Building better documentation. On this page: So why should I care? What is documentation? Types of documentation Creating documentation.

So why should I care? Exert less mental energy Get work done without thinking too hard and exerting the least amount of effort possible. Create consistency Ensure that the same information, processes, and plans are being consumed by your readers in a consistent way. Minimize workload Onboard teammates quickly and efficiently so they can start getting work done right away. Improve company branding Make a statement about how you treat your external customers and internal employees by being supportive and helpful.

All documentation should aim to accomplish 2 main things: 1. Inform users. Types of documentation As we've previously mentioned, documentation comes in all shapes and sizes, internal and external.

Internal documentation. Team documentation Team documentation helps illuminate the work that's being done so teams can, well, work as a team. See example. Reference documentation Reference documentation educates the company on important topics, processes, and policies. A wiki can help your organization collect and capture institutional knowledge, assemble content from numerous sources, and share plans and ideas. For example, a corporation can create a company-wide Enterprise wiki where employees can find and contribute the latest, most comprehensive information about corporate activities, benefits, and services.

Or your team can use a wiki to collect information for new team members, to plan a conference, or to collect ideas for a large document or manual. After someone creates a wiki page, another team member can add more content, edit the content, or add supporting links. The community of authors helps to ensure the accuracy and relevance of the content.

Wikis continue to evolve as people add and revise information. Because team members can edit wiki pages without any special editing tools, wikis are a good tool for sharing ideas and collecting information from several people. Team members can easily create links to pages for someone to finish creating later, or links to existing pages, without having to struggle with long web addresses.

The default page type on team sites, and other types of sites, is a wiki page. So in that sense, wiki is everywhere. Because the home page of a team site and the new pages that you create there are automatically wiki pages, you can create a wiki right on your team site without creating other libraries or sites.

New pages are created in the Site Pages library on a team site and you can manage your pages from there. However, the disadvantage to this approach is that you will not have as many specialized options that come with a wiki page library or an Enterprise wiki site. If you know you will be creating many wiki pages or if you want to manage permissions separately for your wiki than for the rest of your site, you have a couple of options, depending on the scale of the wiki you plan to create and the range of options you want:.

Wiki page library A wiki page library is tailored to managing wiki pages and includes special commands on the ribbon for managing page history, permissions, and incoming links to pages. A site owner can create a wiki page library on most sites and get many of the benefits of a traditional wiki. Enterprise wiki An Enterprise wiki is a publishing site for sharing and updating large volumes of information across an enterprise.

If an organization needs a large, centralized knowledge repository that is designed to both store and share information on an enterprise-wide scale, consider using an Enterprise wiki. To learn more information about how to plan and create an Enterprise wiki site, we recommend reading the articles about planning sites and site collections. You need to have permission to create a site, library, or pages. But the good news is, if a site has been shared with you and you have permission to edit it, you most likely have permission to create a wiki.

Permission levels can be customized, but for most sites, you can create a wiki page library if you have the Edit permission level. By default, members of the Site Name Members group have the Edit permission level. You need to have the Full Control permission level to create an Enterprise wiki site, or your administrator must enable self-service site creation. By default, members of the Site Name Owners group have the Full Control permission level, but your site may be set up differently.

To manage permissions for a page in a wiki page library or an Enterprise wiki, a site owner can click the Page Permissions command on the Page tab on the ribbon. Although initially creating the site or library is similar to other sites, adding content to a wiki is different from how you add content to other types of sites.

On a wiki, you usually start by editing the home page and adding placeholder wiki links to other pages that do not exist yet. You can create those other pages as you go or create them later. When you want to create the page that corresponds to a placeholder link, click the link.

The page opens in Edit mode where you can add text and other content such as images. Was this article helpful? If so, please let us know at the bottom of this page. If it wasn't helpful, let us know what was confusing or missing. Please be as specific as possible, and include your version of SharePoint, OS, and browser. We'll use your feedback to double-check the steps, fix errors, and update this article.

Create a wiki page library A team site is a wiki. SharePoint Server Notes: You can configure the settings for the wiki page library, such as permissions, page history, and incoming links, by going to the library and clicking Page in the header.

To insert a picture from your computer, do the following: Click the Picture and then click From Computer. To insert a picture from a web address, do the following: Click Picture and then click From Address. In the Address box, enter the web address where the picture is located. Top of Page. Click Try link to test your link URL. When you're done, save your link.

Click where you want to insert a wiki link. Do one of the following: To select one of the suggested pages, use the arrow keys and then press ENTER, or use the mouse. Your finished page name should be surrounded by double square brackets, like this: [[Page Name]] Tips: To quickly add a link from a wiki page back to the home page for your wiki, type [[Home]].

Here are some examples of links: [[Dogs]] : A link to a page named Dogs in the same folder. Go to the page that has the placeholder link. Click the placeholder wiki link. In the Add a page window, click Create.

Add the content that you want to the new page and save it. Do one of the following: To edit the path of the link so that it points to a different page, click between the two sets of double-square brackets [[ and ]] , and then replace the current link with the name of the page that you want to link to.

You can add a hyperlink to a page that is external to your wiki or even external to your site. Add a link to an external page If you are not already editing the wiki page, click Edit. Click where you want to insert the hyperlink. Click where you want to insert the list or library. Click Insert and then click Web Part. Create a wiki page library By default, a team site is a wiki. In the Create dialog box, click Wiki Page Library. Click Create. From the wiki page that you want to edit, click the Page tab on the ribbon.

Click the Check Out button. You can add a picture from your computer or from a Web address directly to your wiki page. To insert a picture from your computer, do the following: Click the Picture button, and then click From Computer. To insert a picture from a Web address, do the following: Click the arrow beneath the Picture button, and then click From Address. In the Address box, enter the Web address where the picture is located. A placeholder wiki link has a dotted line under it.

Add the content that you want to the new page. You can add hyperlink to a page that is external to your wiki or even external to your web site. Click the Insert tab on the ribbon, and then click Link. Click Create to create the list or library and add it to the page. Create a wiki site Before creating a site, make sure that you are at the location on your site where you want to create a new subsite. On the wiki page that you want to edit, click Edit. Type any text you want.

Browse to the picture library that contains the image. Click the picture that you want to use. Navigate to the wiki page where you want to add a picture. Click Edit. In the Alternative Text box, type alternative text to describe the image. Alternative text helps people with screen readers understand the content of pictures. Type the name of the page, surrounded by double square brackets: [[Page Name]] For example, to insert a link to a page called "Training Issues," type [[Training Issues]].

Need more help? Expand your skills. Get new features first. Was this information helpful? Yes No. Thank you! Any more feedback? The more you tell us the more we can help. Can you help us improve? Resolved my issue. Clear instructions.

Easy to follow. No jargon. Pictures helped. Didn't match my screen. Incorrect instructions. Too technical. What will the final product look like? How does the internal architecture function? By creating a software design document, your engineering team and other stakeholders can establish exact expectations for the project before you start coding. SDDs also help streamline the coding process. To create an SDD, you have to think through your entire system architecture before writing any code.

This allows you to anticipate any snags or roadblocks and plan around them. What does a software design document actually look like? While every document will be unique to its project, the overall structure of SDDs is fairly consistent across projects. As you create your own software design document, be sure to include these elements. At the beginning of your SDD, be sure to include the title of your project, the authors of the document, not the software , and the reviewers typically non-engineering stakeholders.

In your functional description, you should cover error handling, one-time startup procedures, user limitations, and other similar details. You just need to discuss a few questions with the client before you start developing. Do certain elements of the interface change animations? Which elements are buttons? How many unique screens can the user navigate to? And, of course, what does all of this actually look like?

As your client shares their vision for the user interface perhaps sending rough sketches , your teams should build out wireframe diagrams. Once these wireframes are approved by the client, include them in the user interface section of your software design document. Learn how to create a low-fidelity wireframe in Lucidchart to include within your software design document. Instead of approaching your project as a single drawn-out process, you might find it helpful to break it down into more manageable pieces.

At the most macro level, you have an overarching goal: What problem is your software addressing? Who will be using it?

Below that, you have a set of milestones.