4 ms·
I've thought about a similar idea; VCS backed documentation tool with an (optional) web based interface. The reason I started thinking about this problem is be
by fuball63 6y ago
I've thought about a similar idea; VCS backed documentation tool with an (optional) web based interface. The reason I started thinking about this problem is because of how code documentation becomes so stale so quickly.
At my job, we try to separate documentation into technical, fast changing, repo specific information in the repo Readme and "how to", reference, big picture documentation into an external tool.
We use Confluence and I have several issues with it. Primarily, the web based editor is terrible and it doesn't let you see access statistics (without a plugin, last time I checked.)
The first contributes to documentation being stale because none of the developers want to futz around with it in addition to their project Readme. The second means that you can't look at the ratio between access and last modified times.
High Access/High Modification: crucial and currently changing information that needs to be monitored for accuracy fairly regularly
Low Access/Low Modification: non crucial, but also probably no longer relevant and is cruft that could be removed.
High Access/Low Modification: important information that may be outdated and should be reviewed.
Low Access/High Modification: potentially indicates a notepad situation that could identify a "knowledge silo" with one developer.
Is there a tool that can do this sort of analysis, offers a web interface for non developers, but also allows local editing?
- Ninjaneered 6y agoIf you're willing to install extensions, MediaWiki has some options that you might be interested in. MediaWiki has a visual editor in addition to mark-up, my preferred way to configure it remembers which editor the user used last, but they can switch when they want. Out of the box, MediaWiki is fairly bare bones, but if you're willing to spend some time on the set-up, it's pretty powerful. For example, page views were removed in MW 1.25, but can be added back using the HitCounters[1] or WireTap[2] extensions. However, the extension I think you might like is called WatchAnalytics[3], it's able to demonstrate how "watched" a wikis pages are, who's watching them, how quickly they're reviewed after being edited, and more. It's really helpful to build a consensus at a company about what's known and provide the metrics to encourage review. [1] https://www.mediawiki.org/wiki/Extension:HitCounters https://www.mediawiki.org/wiki/Extension:HitCounters [2] https://www.mediawiki.org/wiki/Extension:Wiretap https://www.mediawiki.org/wiki/Extension:Wiretap [3] https://www.mediawiki.org/wiki/Extension:WatchAnalytics https://www.mediawiki.org/wiki/Extension:WatchAnalytics
- fuball63 6y agoThanks for the tip!
- Ninjaneered 6y agoOne more tip, you might try using Meza[1], an automated MediaWiki install/deployment tool to get you up and running quickly. It comes pre-baked with several extensions[2] including visual editing and the extensions I mentioned above (WireTap & WatchAnalytics). It was actually created by a talented team at NASA and makes things much easier (including suggested extensions for enterprise use) if you have access to a server. [1] https://www.mediawiki.org/wiki/Meza https://www.mediawiki.org/wiki/Meza [2] https://www.mediawiki.org/wiki/Meza/Extensions_installed_by_default https://www.mediawiki.org/wiki/Meza/Extensions_installed_by_...