{"id":239,"date":"2024-10-23T06:00:00","date_gmt":"2024-10-23T13:00:00","guid":{"rendered":"https:\/\/flenniken.net\/blog\/?p=239"},"modified":"2024-10-22T21:47:48","modified_gmt":"2024-10-23T04:47:48","slug":"wiki-organization","status":"publish","type":"post","link":"https:\/\/flenniken.net\/blog\/wiki-organization\/","title":{"rendered":"Wiki Organization"},"content":{"rendered":"\n<p>I\u2019ve been writing a lot of technical documentation the last few years. I want to share what I\u2019ve learned about organizing a dev department wiki and the way I\u2019ve found that works well. <\/p>\n\n\n\n<p><\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Annotated Link<\/h2>\n\n\n\n<p><\/p>\n\n\n\n<p>The key to organization and making it easier to find information is a good annotated link. <\/p>\n\n\n\n<p><\/p>\n\n\n\n<p>An annotated link is a link to a wiki page and a short sentence that tells what the page is about.  For example:<\/p>\n\n\n\n<p><\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Wiki Style Guide \u2014 how to write a wiki page and keep the wiki organized.<\/li>\n<\/ul>\n\n\n\n<p><\/p>\n\n\n\n<p>The annotated link starts with an asterisk (so it is a bullet point) followed by two dashes then the short sentence that tells what it is about. <\/p>\n\n\n\n<p><\/p>\n\n\n\n<p>You use this annotated link wherever you reference the page. <\/p>\n\n\n\n<p><\/p>\n\n\n\n<p>One benefit I\u2019ve found is the process of writing a good annotation you end up writing a better wiki page because you have a better idea what it is about.  You should be able to use the annotation sentence as the topic sentence of the page. <\/p>\n\n\n\n<p><\/p>\n\n\n\n<p>In the annotated link you use related terms and keywords so it is easier to find it by keyword searching. <\/p>\n\n\n\n<p><\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Index<\/h2>\n\n\n\n<p><\/p>\n\n\n\n<p>The next element for finding information is an index. The index contains all the annotated links in one big list. To find information in the index you use the browser text search. <\/p>\n\n\n\n<p><\/p>\n\n\n\n<p>As you write a new page, you add its annotated link to the bottom of the index. This gives you a relative time line history of when the pages were written.  You look at the bottom to find new information. <\/p>\n\n\n\n<p><\/p>\n\n\n\n<p>Don\u2019t alphabetize the list. Unlike a book index you can instantly find using text search. <\/p>\n\n\n\n<p><\/p>\n\n\n\n<p>One big list wouldn\u2019t scale to wikipedia but it works well for a dev wiki. I\u2019m using one with about a thousand links. <\/p>\n\n\n\n<p><\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Table of Contents<\/h2>\n\n\n\n<p>The final element is the table of contents. Again you use the annotated links to build the table. <\/p>\n\n\n\n<p>The hierarchy of the table is two levels first main pages then topic pages. The table of contents is an alphabetized list of main pages.<\/p>\n\n\n\n<p>Here is an outline of the table of contents:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>Table of Contents\n  * topic a \u2014 main page for topic a\n  * topic b \u2014 main page for topic b\n  * topic c \u2014 main page for topic c\n  \u2026<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\">Main Page<\/h2>\n\n\n\n<p>A \u201cmain\u201d page contains a list of annotated links of related pages of a particular topic. You alphabetize these links. Each link points to a topic page.<\/p>\n\n\n\n<p><\/p>\n\n\n\n<p>A main page ends with a See Also section.  It points back to the table of contents.<\/p>\n\n\n\n<p><\/p>\n\n\n\n<p>Below is the outline of the Wiki Information main page. It has annotated links to a few topic pages including the Wiki Style Guide and ending with a see also section. <\/p>\n\n\n\n<p><\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>Wiki Information\n  * Topic Page A \u2014 how to do topic a.\n  * Topic Page B \u2014 how to do topic b.\n  * Topic Page C \u2014 how to do topic c.\n  * Wiki Style Guide \u2014 how to write a wiki page and keep the wiki organized.\n  * Topic Page Z \u2014 how to do topic z.\n  = See Also =\n    * Table of Contents \u2014 the table of contents for this wiki. <\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\">Topic Page<\/h2>\n\n\n\n<p>A topic page contains the meat of the wiki. It tells you how to do something or explains a topic. <\/p>\n\n\n\n<p>A topic page ends with a \u201cSee Also\u201d section. The first link of the section contains a link back to its main page. If the page is in multiple main pages, it has multiple links back. This is important for navigation. Once you find one page of a topic, you can find all related pages through these links. <\/p>\n\n\n\n<p><\/p>\n\n\n\n<p>Say you have a Wiki Style Guide topic page. The topic page outline would look like the following:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>Wiki Style Guide\n  = Summary =\n  = Section 1 =\n  = Section 2 =\n  = Section 3 =\n  = See Also =\n    * Wiki Information \u2014 main page for topics about the using the wiki and writing good wiki pages. <\/code><\/pre>\n","protected":false},"excerpt":{"rendered":"<p>I\u2019ve been writing a lot of technical documentation the last few years. I want to share what I\u2019ve learned about organizing a dev department wiki and the way I\u2019ve found that works well. Annotated Link The key to organization and &hellip; <a href=\"https:\/\/flenniken.net\/blog\/wiki-organization\/\">Continue reading <span class=\"meta-nav\">&rarr;<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[29],"class_list":["post-239","post","type-post","status-publish","format-standard","hentry","category-uncategorized","tag-wiki"],"_links":{"self":[{"href":"https:\/\/flenniken.net\/blog\/wp-json\/wp\/v2\/posts\/239","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/flenniken.net\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/flenniken.net\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/flenniken.net\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/flenniken.net\/blog\/wp-json\/wp\/v2\/comments?post=239"}],"version-history":[{"count":8,"href":"https:\/\/flenniken.net\/blog\/wp-json\/wp\/v2\/posts\/239\/revisions"}],"predecessor-version":[{"id":257,"href":"https:\/\/flenniken.net\/blog\/wp-json\/wp\/v2\/posts\/239\/revisions\/257"}],"wp:attachment":[{"href":"https:\/\/flenniken.net\/blog\/wp-json\/wp\/v2\/media?parent=239"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/flenniken.net\/blog\/wp-json\/wp\/v2\/categories?post=239"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/flenniken.net\/blog\/wp-json\/wp\/v2\/tags?post=239"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}