3 ms·
We used to use a Mediawiki wiki, which only I would edit. You kind of have to be comfortable with mediawiki syntax (does the job for everything but tables, whic
by vacri 11y ago
We used to use a Mediawiki wiki, which only I would edit. You kind of have to be comfortable with mediawiki syntax (does the job for everything but tables, which suck). So we moved to Confluence, which has a WYSIWYG editor, to encourage more people to document things, upload documents, so on and so forth. Again, I am the only one editing it... so our documentation is "very occasionally write something down, and store it on your laptop or in your private google drive, then spend ages searching for it when someone asks".
So whenever a new staffer comes along, I get asked to give them wiki access... but I'm the only one here that uses my edits (only ops staffer). Sure, have some wiki access, for all the good it will do you!
I really don't recommend our model :)
Anyway, this is an important point: documentation is not free. It takes time. Even shitty documentation takes time. If you want good documentation, you need to budget time away from other tasks. When I used to work in support, the field repair engineers would budget 30% of their hours for doing paperwork - not documentation specifically, but it clearly shows that 'writing stuff' is not something that springs as a natural/free parallel to other activity.
- douche 11y agoThose mediawiki tables... Wikis seem like such a great idea, but I've never seen an implementation that was good enough and low friction enough that people will actually use them. Same for Sharepoint...
- Fannon 11y agoWe use MediaWiki + SMW / Semantic Forms. This allows to define a data model and forms which makes it easy for user to add / write to the wiki in a structured way - and without sitting before a blank page. For free text, the new Visual Editor works also rather well, though it's not easy to setup. The structured information can also be queried, visualized, exported to various data formets etc. To document software projects, I really like to write *executable documentation". E.g. I'm using JSON Schema a lot to define my expected data structures and contracts between modules. Then I write a small program that automatically generates the technical documentation based for me. Humans can still add/annotate to the documentation because it's a wiki (and I can separate between auto-generated and human-generated rather easily, because of queries). So far, I really like this approach as it has the automation of doc generators, the flexibility of wikis. Most of the information is stored/accessible as data / API. The downside of this appraoch is, that this platform takes some time and knowledge to setup and model the data structure / forms. Without those, corporate wikis usually seem to die the "one man show" death you described
- brwr 11y agoWe've already have internal discussions about whether it makes sense to make documentation part of our ticketing system (we use Pivotal Tracker). Everyone seems to agree that it's the only way the docs will ever get updated. 30% is a lot though!
- vacri 11y ago30% is for field repair support guys, who have to fill out full paperwork on every single job (and it's a rule of thumb, not ironclad). Not every software ticket requires that. It's just more to show that documentation requires some time; it's not something that you "just spend +5 minutes on the task and it's there". Minor edits, sure, but not good documentation.