User:Mikedanko/Wiki Organization Notes

From OpenNMS
Jump to navigation Jump to search

10,000 Feet

People coming to the OpenNMS site are probably looking to actually _do_ something, the current structure makes this sort of confusing. Wiki layouts of projects like Fedora are well thought out, designed, and have strict guidelines as to what can go where for very specific reasons -- clarifying the OpenNMS wiki will make life easier for a lot of folks and contribute to the overall involvement in the project.

Current Wiki Analysis

The Popularity Contest

According to Special:PopularPages, besides the main page and the "new wiki" splat, there's really just a few categories of what people are using the wiki and the org site for:

  • Getting OpenNMS
    • No Link, from main page
    • Using the Download link
  • Documentation
  • New and Noteworthy News
  • Installation Instructions
    • Windows (#1 Install Topic, #5 overall)
    • Yum (#2 Install Topic, #11 Overall)
    • Debian (#3 Install Topic, #13 Overall)
    • Generic Installation and Mac installation down the list a bit...
  • Initial Configuration Instructions
    • Discovery
    • Data Collection
    • Events, Polling, etc.
  • Q&A
    • Config FAQ
    • About FAQ
    • Project Defining Information -> The Comparisons
  • Who's Who?/People Info
    • OGP
    • Wall of Cards

Issues

With the re-roll of the wiki around the time of devjam 2010, navigation can be confusing at best, and integration of the .com site with the .org site can actually contribute to this at times. Side bar links cover both general and detailed topics. Some links are completely mislabeled. Much information duplicated around the site many many times, such as download instructions.

Examples

1.) Two links point back to the main wiki page which people probably landed on (see Special:PopularPages). One, the "Wiki" link near the top can be easily missed, the other, "Main Page" isn't very clear as to what it is prior to clicking. The "Home" button doesn't take a user back to the landing spot (wiki home), instead takes them somewhere else. This is a confusing breadcrumb trail, and the way in isn't the way out. Users need to be redirected on entry and link titles need to be clearer.

2.) "Get Involved". This is not a place for API docs or XSD docs. You cannot be involved with API docs, the involvement would be Development. Involvement terms should be verbs.

3.) Official Documentation isn't. The Docu-overview page is linked to as both the official and unofficial documentation source. The category page does an ok job, but there are too many sources of "Documentation". There should be official documentation which is static in nature (git repo to docbook sources?), the "unofficial" wiki docs, and user contributions referred to as User Contributed. The new buttons and footers somewhat help, but they need to be prime targets and not secondary.

4.) The .com v .org contrast, which didn't exist before and is a "good thing", can be confusing. Content that should be static is often dynamic, or listed in several areas, which lead to brain entropy. The overlap is real and needed, but difficult to understand at times and makes site navigation difficult as stated in point #1 for example.

5.) The .org site tells you nothing of what OpenNMS actually is without seriously digging.

Goals

This is the hard part. After doing some free form work to try and create a "better wiki" from scratch, the problems I ran into were multifold. There are some clear-cut goals however.

1.) Have a much clearer landing page. Who we are, What we do, what OpenNMS is, and why we do it all. Jumping points to the most popular content, links to broader categories.

2.) Aim to actually release a proper doc bundle. A mountain, yes, but it's hard to clean up the docs when they never have a permanent home.

3.) Ease navigation. Many pages have reference loops, or can be considered duplicate authoritative sources for the same information.

4.) Remove superfluous pages, like the social media page. It's already on every page header (and doesn't include LinkedIn). Remove unused links or move them to more appropriate places.

5.) Meta-categorize doc content into: Install, Configure, Extend, Develop, and Use.

6.) Consider targeting audiences by community type. NOC, Admin, Engineer, Management. Perhaps a walk-through under features.