Wikis can be very flexible and powerful tools for writing and delivering any kind of documentation. Ensuring that the documentation on a wiki is effective takes a bit of work, but that extra effort focuses that the documentation on the needs of your readers and makes it easy to use. How to use wikis to write documentation 3 tips for effectively using wikis for documentation.
Image credits :. April Killingsworth. Modified by Rikki Endsley. Get the highlights in your inbox every week. Think outside of the "book" I've learned one lesson from spending over 20 years in the trenches a technical writer: No one likes reading thick manuals. Navigation is important Taking a topic-based approach can result in disjointed documentation in which little, if any, continuity between topics exists, but it doesn't have to be that way. What are the elements of good navigation?
They include: A detailed table of contents that readers can access wherever they are on the wiki A set of landing pages containing links to groups of related content for example, installation and upgrade procedures A set of links at the end of each page that point to related information Adding links to your wiki pages involves a lot of manual work, but doing so is worthwhile because it makes your reader's experience much smoother.
Looks can matter Documentation has to have an aesthetic strategy. One final thought Wikis can be very flexible and powerful tools for writing and delivering any kind of documentation.
Topics Documentation. About the author. I don't take myself all that seriously and I do all of my own stunts. More about me. Recommended reading Build a static website with Eleventy. A DevOps guide to documentation. Wikis can also be great for rapidly changing content—development planning, for example. If your project is young and hasn't stabilized yet, writing long-form documentation may not even be possible.
The release notes for the Fedora project start out as wiki pages, which are later converted to a rendered markup language, combining the best of both worlds. The best documentation is what actually gets written, so always favor a wiki over no documentation at all. Because the barrier to entry is so low, using a wiki can be a great way to get lots of content quickly.
Just be prepared to tend the wiki garden. This article is part of the Doc Dish column coordinated by Rikki Endsley. To contribute to this column, submit your story idea or contact us at open opensource. You list 5 reasons why wikis are a popular choice. That's a different issue then you list in your title. I can't see why they "rock" - just pragmatic reasons why they're frequently chosen. I don't think they "rock". They're usually fragmented, doubled, not maintained.
You provide one option for documentation, and then talk about a "decision". Not much of a decision with only one option Also, there are different types of wiki's: DB backed wiki's tend to be the most common, there are so flat file wiki's, like Docuwiki, and other types I'm just not thinking of this early in the morning.
Pros and cons of wikis for documentation 5 reasons wikis rock for documentation. Image credits :. Original photo by mshipp. Modified by Rikki Endsley. Get the highlights in your inbox every week.
Wikis are a popular choice for many open source projects. Struggle to deliver quality software sustainably for the business? Give your development organization research-backed direction on improving practices. Simply answer a few questions to generate a customized, confidential report addressing your challenges. Join Rob Harr in this two-hour workshop to get an inside look at how you can put forecasting at the heart of your business.
Estimations can reoccur many times within a project: kickoff, new feature requests, or even sprint planning.
Every web development project and project team is different. Here are five creative problem-solving techniques we use to tackle web projects. Learn about the Project Management 3 C's—Clarity, Culture, Course Correction—and how these can be applied to your project manager role.
Learn how studios can closely partner with clients, create supportive team structures, and always stay curious to create mutual success.
Learn how to identify software seams and reduce blockers using decomping, static data, development sandboxes, and other strategies. Katie can help.
0コメント