As a user/developer who might contribute to the wiki it would be good to have a well known single obvious place to put info about a specific piece of hardware in a hierarchy with the vendor at the top and the product family below it.
On the detail page for each device or family it might be good to adopt an almost blog like format where notes/problems/examples are clearly marked with the date and version used (and firmware version as well) and newer entries are near the top. That way the reader can see that XXX didn't work in mid 2009 but could be worked around, but in mid 2010 a newer vendor firmware made it work correctly. Both the old and new data are useful to people in different situations. I'll put what I've discovered WRT configuration/etc on the spa 3102 and polycoms 3.2.2 and ip335 issues on a page once the location is pinned down. My experience using an internal engineering wiki (twiki) with several other sr developers working together on a mid size (1.5M kloc) project has been that w/o a full time librarian to keep things in order only really obvious order 'sticks' over time. The only way most people will access the wiki in these days of google is to use full text search, we've gotten good at putting lots of superfluous keywords on our pages so searches will hit and have more or less abandoned all but the most rudimentary top page structure. It helps to require some context on any new page so a searcher can determine if its out of date/irrelevant (like at the top: "This page was created to share info and tips while debugging feature XXX for release YYY in March 2008"). My .02, -Eric Varsanyi On Jan 5, 2010, at 7:10 AM, Scott Lawrence wrote: > On Mon, 2010-01-04 at 13:29 -0600, Josh Patten wrote: > >> I guess now that the holidays are over with it's time to start getting >> back in the swing of things and one thing I think all of us want to see >> is better documentation. > > I've been waiting until people were back from the holidays to take up > this thread again. For my earlier post on this see: > > http://list.sipfoundry.org/archive/sipx-users/msg19879.html > and > http://wiki.sipfoundry.org/display/~xmlscott/Proposed+sipXecs+wiki+organization > > I have a conversion program that will do a first-order migration of the > existing mediawiki content into a space in wiki.sipfoundry.org. The > resulting pages usually require just a little manual tweaking to be good > Confluence content. I'm hoping that we can spread that effort around. > > Before I start that, I'd like to hear some discussion of how the user > documentation in the new wiki should be organized. One of the very nice > features of Confluence is that there's hierarchy to the pages - each > page has a parent, and siblings are ordered. The theme I've installed > makes that tree visible on the left side, with the usual ability to > expose or hide branches at each level (the default width of that tree > display is pretty wide, but you can narrow it by dragging the border > between the left side nav panel and the main content area, or by > clicking on a small windowpane icon near the top right of the page). > > As we clean up and update migrated content pages and move them into the > new documentation, it would be good to already have at least a notion of > what the top level sections should be in that hierarchy. I'm thinkging > something along the lines of (a grossly incomplete list): > > - Network Infrastructure > (DNS, DHCP, QoS, PoE) > - Users and Internal Call Routing > - PSTN Connectivity > > ... but what I really want to know is what existing administrators > think. What are your top level section suggestions? > > > > _______________________________________________ > sipx-users mailing list [email protected] > List Archive: http://list.sipfoundry.org/archive/sipx-users > Unsubscribe: http://list.sipfoundry.org/mailman/listinfo/sipx-users > sipXecs IP PBX -- http://www.sipfoundry.org/ _______________________________________________ sipx-users mailing list [email protected] List Archive: http://list.sipfoundry.org/archive/sipx-users Unsubscribe: http://list.sipfoundry.org/mailman/listinfo/sipx-users sipXecs IP PBX -- http://www.sipfoundry.org/
