101–110 of 163 posts
An open source alternative I've used in the past is Askbot: https://askbot.com/ It's built on Django, and covers all of the standard Q&A features that I've needed to use.
My question is, is this better than your self-hosted wiki? At least that's cheaper and isn't a vendor lock-in. Sure wiki doesn't have the best possible UI and the UX might be too so-and-so. If I were in a position to buy this kind of service I'd still want something more out of it. Maybe if it offered a way to export Slack threads into SO as questions so they wouldn't get lost. Sure you could generate those questions…
First, it gives you a template to post in - you are not given a blank page and told "document this"
Second, it encourages you to document single, smaller, focused pieces of information. You're not being asked or expected to write a multipage document, you're being asked to write a single entry in what essentially is a crowd sourced FAQ.
One thing the SO approach also does is that it respects the content that each person posts. If I post an answer, only I can modify it. Nobody will modify my answer to reflect what they think, and make it seem as if I was presenting a different solution that what I suggested. What people with alternative ideas CAN do though is post alternative answers, or comment on my answer with suggested changes.
I have thought about building this so many times. I think there is a need for it, particularly for non-technical teams where processes don't evolve that fast, but adoption will be hard to ignite.
Seems like "yet another tool to try to offset the problem of requirements, code, and architectural decisions not being adequately documented for future staff to understand." Sometimes I wonder if software teams should add technical writers embed with developers, architects, QA, and BA assets to actually document All The Things and keep documentation up to date. Yes, that will mean re-writing documentations as people…
Pushing the need for clear documentation is a battle I find myself frequently fighting. Many devs just aren't sure how to prioritize it or write it, and even worse, many seem to have absorbed the idea that code should be self documenting and that comments are a code smell. Whoever is responsible for the idea that comments are code smell deserves to receive all future vitriolic emails from anyone who ever stumbles int…
I have read to many comments stating the obvious or that are just plain wrong.
No comments are better than comments with errors. The code is the only true fact.
Create massive comment blocks to explain things if you have to but put it all there in the code, next to the things that matter. Then it has half a chance of still being accurate. And, you know exactly where the documentation is. If the code becomes obsolete and is removed, you naturally strip out documentation that is no longer relevant at the same time.
Revision control log messages are important. I so hate lazy messages; if you change 5 files in random ways and your message is “fixed bug”, I think you should be fired. If it’s in the issue tracker, your log had better mention the number. Add a paragraph daring to explain what the hell you did so I can read a sensible log history and figure out what happened when.
Issue trackers are useful for capturing every relevant detail, especially new information that is found while the bug is being investigated. The bug might come up again, and details can help to sort it out.
If its using logical separation on a shared SQL server, then is it really a "dedicated network"?
Totally misread the title and thought it was for "Teens". LOL
>No more digging through stale wikis
Over the years I’ve concluded, reluctantly, that the ONLY documentation solutions that matter are the code, revision control logs and issue trackers. Create massive comment blocks to explain things if you have to but put it all there in the code, next to the things that matter. Then it has half a chance of still being accurate. And, you know exactly where the documentation is. If the code becomes obsolete and is remo…
Because an API reference is a very poor doc.
We've been running this in beta for a couple months now, happy to answer questions about it. The SO team has been super helpful during the process.
Is this better than finding the right person to ask, or posting in slack or something?
In my org we have a wiki on topics and if that fails an "experts" list with people to contact for further help. There is also a yammer group for asking questions, but that is rarely used. I think this could be helpful, but whether or not it's worth the cost would be a question for someone else.