Ask HN: How does your team handle knowledge documentation?

111 点作者 dalemyers超过 7 年前

We are currently going through a rethink of our documentation (not for customers, just our internal processes, tools, etc.). Currently we have a docs directory in the root of our project repository which holds a bunch of markdown files, but we are beginning to grow out of this. Keeping links accurate and update to date isn't too much of a challenge, it's the barrier to entry. Filing a PR to make a minor documentation change is just too much. We could have the documentation in a separate repository, but if we are going to be making this leap, we want to be sure we are using the right tools for the jobs.The way we see it, we are going to end up requiring at least 2 different types of documentation. The first is our deep documentation of our tools. This explains exactly what it is, how it works, etc. and is designed for people who want to work on these sorts of tools, not with them. The second is a quick fire Q&A. "I'm having issue X, how do I fix it?" Think StackOverflow.So, what does your team do for these challenges? How effective is your solution? What do you think would be better?

40 条评论

ryanmonroe超过 7 年前

I work at a large bank. Mostly people hold all relevant knowledge in their own head, and when they receive a request for information they only respond if their manager knows yours. Then, they will mostly refuse to create any type of actual document and instead request that you set up a meeting with them through Outlook. They are of course completely booked on their Outlook calendar for at least the next few weeks, and then when you do get to talk to them they use obtuse department-specific acronyms as much as possible so that by the time you've started to understand the surface of their answer they have to leave for an urgent meeting.

评论 #15663917 未加载

评论 #15639294 未加载

评论 #15640318 未加载

评论 #15639342 未加载

评论 #15638667 未加载

iandanforth超过 7 年前

Solution: Hire a librarian. I'm not kidding in any way. They are massively underemployed and are very good at exactly this task. Back at PBwiki we hired a librarian who not only organized all the things but ended up running and building our support organization.Do not tell them what tool to use, let them own your knowledge base and make their requests for information understood to be P1 priority.

评论 #15639520 未加载

评论 #15638707 未加载

评论 #15641196 未加载

clintonb超过 7 年前

At Vistaprint, we used MediaWiki, hired a dedicated librarian, and, most importantly, had a culture of documenting everything on the wiki. The last point is most important. Everyone in the organization _must_ adopt the mindset of checking the wiki first. If the information is not on the wiki, figure it out, and put on the wiki. I vaguely remember wiki articles even being a (minor) metric for annual reviews. At one point, Vistaprint tried SharePoint but we quickly went back to MediaWiki.At edX we have information spread between Confluence and Google Drive. Search is not ideal for either. Information sharing is not great.

jhchen超过 7 年前

Disclosure: I am the founder of a company that aims to solve this first documentation case you pose. But the process of validating this problem and get early feedback on our solution, I interviewed to dozens of companies to learn about their tools and processes, and hopefully some of that can be helpful here.The information split is very much as you describe between canonical and ephemeral. For the first case, the defacto tool for medium size companies (25-1000) is Confluence (large companies lean towards a custom intranet). Confluence is accessible to the entire company, not just engineers with git and markdown knowhow, it is also well established, very reasonably priced and can be deployed on cloud or on premise. There are drawbacks such poor search and complex organization that makes it hard to find anything, but there is not a clearly better solution at the moment, though there are a few startups like mine trying to change that.For the second case, companies have tried to deploy an internal StackOverflow / Quora, some homegrown or using open source tool but unless tied to a specific workflow (like all hands Q/A), they are eventually abandoned. The issue is a lot of duplication of content that also changes very often. So long term storage is not as valuable as just removing the initial friction and what seems to work best is an ephemeral solution like a dedicated Slack/Hipchat/Teams/Mattermost/Gitter/Zulip channel.

评论 #15638997 未加载

rubidium超过 7 年前

The PR isn't your problem. There will be some other other problem you'll find with any new documentation system. The root cause is keeping documentation up to date is universally a pain. Unless you have it as (part of) someones job, it always will be subject to decay.If someone has "solved" creating a good way to capture tribal knowledge, I'm all ears. But it's not the tools being used that are the issue or the solution.

评论 #15639905 未加载

iamNumber4超过 7 年前

In my opinion you are on the right track with the project holding a Documentation folder and the markdown files. Keep it all together or you will have yet another place to maintain.I would suggest adding the use of Doxygen to your projects. It supports Markdown files as well as Markdown syntax in your code comments. You might find that a lot of what you are documenting in the separate .md files could be a notes or remarks section of your method class comments. This will remove the separation of technical documentation vs. help/FAQ comments by doing all of the documentation in the code. You can then add Doxygen to your build, so that building the project refreshes the documentation. Doxygen can be configured to produce a online html version that can be deployed to an internal web server for quick reference. It can also build .pdf, rich text documents, and unix man pages.Then if you use Continuous integration/deployment, when you deploy to test, UAT, then eventually production you deploy the official documentation that was generated.The challenge with all documentation, is, Actually doing it. So it should be part of your SDLC documentation and process. the project/task/request is not done until documentation updated. Make it a checklist item that needs to be reviewed in code reviews. Doing the technical and help/FAQ all in code comments makes that easy.cheers!

评论 #15637462 未加载

throwayit超过 7 年前

Our company uses Confluence and I highly recommend it. I think it does a very good for keeping your documentation "fresh" because:* It's easy to search and find things* It's easy to be notified of updates* It's easy to comment & edit (for both non technical and technical members)* It's easy to create quick documentation through the Q&A product and use the wiki for longer documentationThe main cons I've found with Confluence is:* The general UX is weak (this is the case across all Atlassian products in my opinion)* The markup language is not markdown* The edit & save UX is a bit too heavy, your changes don't get saved automatically but rather it requires a separate button change. So documentation changes are a bit slower than something like Google DocsDespite these cons, Confluence has been great for us. However, in order for any tool to work there also has to be a cultural shift. Our company is very good about:1) Keeping knowledge not silo'd in brains of devs or other tools. So whenever I ask any senior dev a basic question like "How do I get unit test coverage?" they will immediately link you to a confluence Q&A answer or if one isn't created they will give you the solution and immediately ask you to create a confluence question.2) Not spreading knowledge across other tools - any process, decision, design, etc. is required to be in Confluence. Any thing in Slack, Email, or Google Drive is immediately asked to be moved into Confluence.

bastijn超过 7 年前

I work in a department that develops and maintains an internal SDK used by internal BIUs to develop medical applications. Size of codebase is well over 1 Million LoC.We heavily user source code documentation for all public API which is enforced by our internal build tools (build breaks when undocumented code is found) and the review process (to check if documentation is proper). We have a searchable themed MkDocs page with a large number of “how to properly document X”. Reviewers actively place links to these pages in the reviews where source code documentation is not proper (style issues, lacking, no examples, etc).Goal is here to have a proper MSDN like source code documentation and site generated by Doxygen. Each release gets its own documentation, which is easy as it is just a source control revision. A second goal is to have most of the documentation as close to the code as possible so it actually stays well updated.Next to this we have a developer portal which is based on manually written markdown files. We are currently in the process of replacing our existing media wiki pages into markdown as well. Markdown is quite powerful as most people can easily read it, even with just notepad. In addition it converts to anything so it feels a bit more future proof. Right now we put it in a slightly extended mkdocs served site. We extended a bit for versioning and a landing page that links to separate mkdocs sites as the navigation becomes too cluttered if we put all of our layers and components in one site. Better to branch Early is what we found. So separate sites for database, infrastructure, system (multi-subsystem deployments), application development (wpf, HTML5,..),and for each subsystem (printing, auditing, reporting, data server, ...).The problem is already we notice the manual markdown is not properly maintained. I think this is a problem you never solve unless you hire people to do it full time. I.e technical writers.My personal opinion is that a stack overflow enterprise (on-premis SO) is more powerful. Nowadays people want to know “how” instead of “what”. A Q&A site with tons of questions and answers is much better than a one-way written developer portal. Also, other people outside of our department could also answer questions for us. As a benefit you learn where people struggle with your API or use it for things it was not developed for. Feedback is great here.

评论 #15646802 未加载

billconan超过 7 年前

We use mediawiki and and recently IT invested in confluence.I hate it, because it's slow.but I do see it has some benefits, for example, it automatically generates a content table. so content discovery is easier. it is also designed to be a document system for a software company. you can use it to create meeting notes and tag people.but overall, I liked mediawiki, the problem with it is, it's hard to make sure things are up-to-date. and it's difficult to do content discovery.

评论 #15638185 未加载

评论 #15638601 未加载

评论 #15638444 未加载

评论 #15638712 未加载

评论 #15638370 未加载

wink超过 7 年前

How? Badly.Right now it's a GitHub wiki in our "infrastructure" repo (which is basically all the bits and pieces that don't fit anywhere and don't have a proper repo of their own). We migrated to this from: "several github wikis, each in the repo of the project" - but often you have overlap and it was bad to find stuff.Pros:- easy backup (git clone)- markdown- easy to get started, "good enough"Meh:- searchable only with a browser extensionContra:- some coworkers don't like the github wikiMy dream (never happened in any company as of now) would be a single document (think: the manual), hopefully editable in a proper way (I am not sure if checking in changes in a doc/ folder in a code repo is the way to go for <10-20 people) that's hopefully displayable in a browser (and not a PDF, and ESPECIALLY not a Google doc) with cross-references.

评论 #15638255 未加载

评论 #15638643 未加载

评论 #15638335 未加载

pedrorijo91超过 7 年前

Don't use confluence :( In every team I've been, confluence feels like an huge hole, we can never find what we are looking for...

评论 #15637567 未加载

评论 #15645101 未加载

评论 #15638088 未加载

ifoundthetao超过 7 年前

I have had great success with Mediawiki and Slate. With Mediawiki, you can use Categories, ex: [[Category:NameHere]], and templates (don't forget to update the CSS) for great organization and consistency. The usage of templates will allow you to be DRY, so if you update the template, where it is embedded will update too.And Slate was just a pleasure to work with.

评论 #15638840 未加载

vijaykodam超过 7 年前

If you want to maintain documentation for different versions of the same software then consider AsciiBinder. <a href="http://asciibinder.org/" rel="nofollow">http://asciibinder.org/</a>For example, Openshift Origin documentation uses it: <a href="https://docs.openshift.org/3.6/architecture/index.html" rel="nofollow">https://docs.openshift.org/3.6/architecture/index.html</a>There is Mkdocs (<a href="http://www.mkdocs.org/" rel="nofollow">http://www.mkdocs.org/</a>) which is a static site generator targeted towards project documentation. This is more straight-forward and easier to maintain. Both are open source software. You can give them a try and see if you can tailor them to your needs.

thisisit超过 7 年前

From what I have seen creating up to date documents is considered superfluous. There are tons of excuses for why people are not updating the documents. Raising a PR for small changes is one of those excuses.Any tool you find will have it's own version control restrictions. People will use that as a crutch to say - Well, the tool x has steps a, b, c which is too much of hassle for a minor change.This cannot be solved by using better tools or solutions.To give examples from my experience:One of the places where I saw the best documentation was at a bank. Every project came with specific amount of time dedicated to updating documentation. This ensured people don't complain about not having time or the process being tedious etc.Though as there was no time allocated for peer review of document control - It did not stop people from being lazy or creating dependencies by knowingly adding generic information in the document.In worst of places, a software product company - documentation was looked down upon. Everyone was more than happy to "set up time to discuss" than put actual effort in good documentation. As I joined after the aforementioned bank, I had a habit of abhorring meetings and creating up to date document which was shared with the team.The end result was that people still wanted to have meetings. On being told, I shared document with relevant info with them, they used act surprised and ask to share the document again.

kusmi超过 7 年前

Alfresco is an open source Enterprise content management software which has frontend UI called Alfresco Share. The installation is simple using their all inclusive executable which bundles the server, database, and Solr for searching any and all data. It also has this concept of business workflows which you say is a pain point for you. Each document can have workflows assigned to it at which point it has a life of it's own, passing from user to user, emailing itself, tagging itself, etc. There is a learning curve on the dev side, especially if you aren't Java savvy, but once you get the hang of it it's very powerful. I've personally written an API in Lua for syncing documents. I assign bot accounts from the Share UI which are given permission to crawl and sync directories to bot accounts on the server (origin server or external server), and each bot has a job to do on each document it gets, for which it writes and dispatches a service with systemd, then uploads the processed documents back to alfresco. And this is probably 1% of what Alfresco is actually capable of (and my implemention reeks of hackiness, because I hate Java). A team of devs is bound to get more use out of it.

gtf21超过 7 年前

TL;DR* we use Slate for API docs, Google Sites for company documentation (and some Google Docs) * am thinking about using a forum for Q&A e.g. Discourse [2]Longer:We've also been going through some thinking on this. At the moment we have an API docs page using Slate, and a Google Sites site which contains a whole raft of documentation. We still have some stuff in Google Docs as well.Our problem is that not all the team is part of Engineering, so keeping stuff in the repo isn't really ideal (hard to edit). Google Sites is fine but its main selling point is easy access to Google Auth. I have a thread on HN about this [1].One of the things I have been thinking of is setting up a forum like Discourse [2] for Q&A. Sales often has product-based questions, and vice-versa. In my view, this beats other ways of asking questions (e.g. Slack) because there's no time pressure to answer, and unlike "office-hours" style meetings, it's automatically documented. The only problem is that it is yet another tool.[1]: <a href="https://news.ycombinator.com/item?id=12540678" rel="nofollow">https://news.ycombinator.com/item?id=12540678</a> [2]: <a href="https://discourse.org" rel="nofollow">https://discourse.org</a>

评论 #15637530 未加载

flarg超过 7 年前

Have done this role a couple of times. You need to make one person responsible for documentation and traceability, because collaborative editing in a wiki like tool without some editorial oversight and organisation leads to problems later on. The tool really doesn't matter, Confluence works well with Jira, pwiki is nice to use, even sharepoint works in a pinch. Heck, I've even used Enterprise Architect and Mindjet MindManager!

helpsite超过 7 年前

We have a lot of teams using HelpSite.io [1] for this sort of thing. Originally designed for customer-facing FAQs, we also support the same format for internal knowledge bases. We didn't originally intend to support such use cases, but it turned out a lot of people really like our format for internal company docs as well.[1] <a href="https://helpsite.io" rel="nofollow">https://helpsite.io</a>

allan_s超过 7 年前

we have a 2 repository in a gitlab group named "knowledge base", one for public information, one for private information. AND we use a opensource stakcoverflow clone (askbot)for the git repositoriesso that developers works with markdown files, it can be git cloned, it can be grepped, but it can also be rendered in the gitlab website, and most importantly compared to other wiki's or even gitlab's wiki, you can make merge request, so that,<pre><code> * if you fear to put an incomplete things, at most it will be in a MR and get reviewed (or never) but at least it's somewhere else than in your head * all knowledge merged has been known to be there by someone else, so that it's ot just a wiki full of hidden gems that everyone has buried and nobody else know it exists </code></pre> This way you have encyclopedic knowledge of "how to put a new project in our CI/CD pipeline" or "list of horrors in project X that you want to delete, but hey that's not so simple and here's why"the stackoverflow clone on the other hand is here to answer the question everybody ask, from the new employee to the famous "oh why god already do we have to do this command everytime e deploy, I remember John explained it to me one day?" the stackoverflow links extensively to the repository for the "if you want to know more"we also put as much as possible the "as of march 2017" marker, to always remember people that information rotthings we also do:every todo in the code has with it a link to the corresponding issue in the tracker, so that when you have 10 minutes to kill, you can check the tracker for "TODO" issues, and grep "TODO #42" in the code

hv23超过 7 年前

We just started using Guru (getguru.com) for our 13-person remote team (trydesignlab.com), and it's been quite effective. Some key features that we love:- Simple UI with well-known metaphors like cards and collections — each task or process you have as a company can live in a separate card- Tagging combined with lightning-fast search- A bookmarklet that allows you to search your Guru knowledge base from any other site you're on (really handy for our support agents who want to look up a manual process without leaving their support workflow in Zendesk)- A "verification" workflow that ensures your knowledge base is up-to-date (previously a huge issue in any sort of wiki / document-based solution — you never know if what you're reading is the latest piece of info, or whether it's been updated since). Cards can be assigned to an owner who can be reminded to verify the information on a periodic basis (e.g. every 2 weeks, 4 weeks, etc.), and anyone viewing a card knows whether it's been recently verified- The ability to ask questions to individuals / groups within Guru, with answers turned into new cards. Instead of tapping someone's shoulder (or sending them a Slack message), we now ask for info within Guru, organically growing our team's shared knowledge base over timeOverall this has been a tremendous find for us. We had a number of core processes (support, operations, payments, dev, marketing, sales) that lived in various Google Docs (including one monolithic 'Process Guide' doc), but that system was growing extremely cumbersome to use. We strongly considered Confluence, but stayed away after a short trial revealed how bloated the product was — we knew ramping the team up would be a nightmare.So far Guru's been a winner — would recommend giving it a spin.

marpstar超过 7 年前

We use Jingo (<a href="https://github.com/claudioc/jingo" rel="nofollow">https://github.com/claudioc/jingo</a>), which is inspired by GitHub's wiki (i.e. is a git repo itself) but with has search function. It's not the best experience on the planet, but it works and is easy to self-host.

cableshaft超过 7 年前

We have a 'this person better not be hit by a bus or quit on us' policy, or nearly so.We have people get assigned tasks from other projects from time to time, and they start picking up bits and pieces of the projects from that. And we have an internal wiki that documents some things that people aren't very good about keeping up to date or making it comprehensive.Also some of our software has gone through rewrites that has cleaned up the architecture and made them easier to understand and work with, without documentation.But there's still way too much locked in people's heads. We've lost quite a bit of it, too, as people have left over time. I know we're trying to convince a client to shift over to newer versions of our software, because we no longer have anyone that knows anything about the tech the legacy legacy software was written in (it's legacy software that predates our existing legacy software).

melissam超过 7 年前

We are using Jive for all of our internal documentation which works really well for us. For deep documentation, both new document requests and document updates are submitted using a built-in "Ideas" feature. "Ideas" can include plain text, links, images, or videos, and can be submitted by anyone in the company. With this information, we can create a new document, save it in Jive, and then respond to the "Idea" with a "The document is done and here's the link to it" comment. For quick fire Q&A, we've created a page in Jive that uses built-in "Questions" and "Answers" features, again, accessible to anyone in the company. Jive's search feature is pretty robust (keyword-indexes anything you add to it without having to create tags, though you can add tags if you want).

Jeff_Brown超过 7 年前

For Semantic Synchrony[1], we keep our notes in Semantic Synchrony, a knowledge graph server (written in Java, using Gremlin and Neo4j) and client (Emacs). It allows for selective sharing, and you can connect your private notes to your shared notes however you like -- for instance, I've got a lot of "half-formed hypothesis" notes that I don't think are worth anybody else's time, so I keep those private. It eliminates the dead link problem, and the linearity constraints that trees (let alone flat folders or text files) impose.It's open-source, with a lot of features, and well documented.[1] <a href="https://github.com/synchrony/smsn/wiki" rel="nofollow">https://github.com/synchrony/smsn/wiki</a>

Ninjaneered超过 7 年前

For just files (Word, Excel, CAD, pdf, PowerPoint, etc.) PDM/PLM software is amazing (some top products include Teamcenter, Windchill, & Enovia). They are tailor made to store the versions (including mark-ups) and provide workfows for approval, since they are born out of the need to store CAD parts/assemblies that have strictly defined parent/child relationships, they have no problems doing the same for more simple files.For the "why" or "knowledge capture", I don't think you can do better than a Wiki and the dominant enterprise Wiki is most certainly MediaWiki. With extensions for improved searching, visual editor, etc., corporate wikis are more powerful and easier than ever to use.

PeOe超过 7 年前

Hey, I can recommend <a href="https://zenkit.com" rel="nofollow">https://zenkit.com</a> . It´s an all-in-one project management platform with additional handy features for knowledge management. Basically, you can create a collection of all your data and add labels to keep everything organized. The collaborative features allow you to invite your team. Other functions like the global search feature lets you search through the whole app and find information you need (great for FAQ´s - type in a problem and get the documented problem + solution). Also, you can link the tool to over 750 other tools with Zapier and integrate your Google Calendar. Disclaimer: I work at Zenkit.

andygcook超过 7 年前

Andy from Tettra here with some shameless self promotion:My startup is actually working on this exact problem: <a href="https://tettra.co" rel="nofollow">https://tettra.co</a>Our philosophy is that knowledge should be fast to capture, accessible from your communication tools (Slack, etc) and open by default for everyone on your team to suggest edits because most knowledge goes stale in other systems.Would love feedback from the HN community. We're documentation geeks here and love talking about this stuff.If you're interested in using the product, we can offer a special HN discount of 20% off the first three months. Just shoot us a message in the chat. I'm on there right now.

评论 #15638781 未加载

ecesena超过 7 年前

We use a wiki where everybody can update, without any review process.My personal preference is to try to write the docs from a "customer" perspective, i.e. not for me that I know the system, but from the perspective of another employee that sees an issue and finds my page.This means:- keywords in the title, so the search autocomplete hopefully will find the page in the first results- short and sweet, meaning that if a process is more than 3-5 steps, the person won't read/understand it. It's better to improve the process than to provide better docs- when I read something that doesn't work, I do my best to fix it, even if I'm in a rush

dmuth超过 7 年前

I work for a Fortune 50 and we use Confluence. For us it works well, because we have more teams here than I can count, and people move between teams (and teams move between business units) all the time. So the standard rule is that if you build something, you are expected to document it in the Wiki.About the only downside is that sometimes documentation gets outdated and you have to hunt down the current version of a process, but that beats the alternative, where nothing is documented.

iscomad超过 7 年前

You can try forcing people to write documentation for every new feature they make. Do not let merging without a documentation. Added major feature - ask them to write a post about it on some documentation platform (for example, Confluence). Old methods could be documented whenever you interact with it. Step by step, slowly but surely you're gonna cover your project with good doc

thomasswilliams超过 7 年前

Small IT team, in public health, using MediaWiki on Windows.Search was underwhelming for our 400 or so pages, so we tuned an old MW extension called RigorousSearch, see <a href="https://github.com/thomasswilliams/RigorousSearch-MediaWiki-extension-updated-for-MediaWiki-1.28" rel="nofollow">https://github.com/thomasswilliams/RigorousSearch-MediaWiki-...</a>

oschn超过 7 年前

We used MediaWiki for documentations, however we were very unhappy with it. We have almost all an computer science background, but did not like the MediaWiki syntax and the interface.We created Teamemo (<a href="https://teamemo.com" rel="nofollow">https://teamemo.com</a>) because knowledge management should be easy, fast and fun.

评论 #15674270 未加载

tschlossmacher超过 7 年前

We use a mixture of Asana and Google Drive.Asana is an amazing tool to store information as well as create a unified workspace where all members can share work, collaborate on projects/tasks, or have a knowledge repository. Would definitely recommend!

omerg超过 7 年前

Hey everyone :)My name is Omer and I am currently building a knowledge documentation solution called Scribe (formerly Mindflow.ai).Scribe runs in the background of your development environment and creates documentation based on your workflow. Additionally, we allow for users to easily create their own documentation in an intuitive, easily searchable fashion.During Y Combinators Startup School we launched our Alpha product, and we are currently building the beta version of our product. If this sounds like it can help, you're more than welcome to sign up!<a href="http://mindflowai.com" rel="nofollow">http://mindflowai.com</a>

afarrell超过 7 年前

Tangent: I remember the first time I used Quora, thinking that it had a great model of content discovery and collaborative answering — that it would be fantastic if they let companies deploy internal versions of it. Now that Quora has been around for 7 years and has clearly decided not to do this but instead to make money by , does anyone have any guesses as to why they decided not to?

评论 #15638316 未加载

rwc超过 7 年前

Nuclino has been a winner for us.

voltagex_超过 7 年前

OneNote - it might not be excellent, but it's got a super low barrier to entry.

bpyne超过 7 年前

Documentation, the thing most agree is a good idea, but nobody wants to do. It's a nuanced subject.TOOLSUntil recently, we used a combination of Documentum and EPM (Enterprise Project Manager). The intended workflow was to have all documents start in EPM as part of the initial project implementing/building whatever product. When the project closed then the developer was to copy the documents across to Documentum. It was simple in concept. Due to technical shortcomings, it was not. I stopped even trying around 3-4 years ago.Documentum was a technical horror show. Ten years ago, and for a long time afterward, it supported only one browser, I believe IE. Architecturally, it seemed to use a Java applet for login and, upon successful login, it downloaded an app. Of course, the app wanted a specific version of the JRE locally. But, the real nightmare was authorization. One day you had permissions to update “cabinets” for your documentation. The next day you didn’t. No explanation.EPM had authorization issues similar to Documentum’s with the added bonus of a project’s link not working all the time. One day you could use the link, which the PM sent out at the start of a project, to access the project workspace. The next day you couldn’t find the project workspace.Currently, we're moving into a SharePoint site that is more promising. It provides Wiki capability for quick reference items, as well as, a repo for more involved documentation. Apparently, it provides versioning, but we haven't explored it yet.TYPESPart of the problem with the subject of documentation is that different groups want different types of documentation. Somehow, the developer is supposed to understand the needs of each group and produce a document tailored to those needs.Operational people want information on jobs and job dependencies. Support people want lists of things to check and try in case errors occur. (Developers are inherently bad at documentation for customer support. The problem is that we know how the system is supposed to work, so we’re blind to its shortcomings until a user finds them. Rather than my writing a support document upfront, I prefer meeting support people periodically so they can ask questions and develop their own document.)Management wants everything, all at once. They want it in the amount they want it, summarized, but detailed enough that they can feel like they’re a help during outages and architectural meetings alike.Users want to know every step for every task they need to accomplish, as well as, what to do in any anomaly, like not paying attention to dialog boxes and hitting “Save” to commit information that they didn’t want to commit.ISSUESThe major issues, for me, are keeping documentation current and writing for such varied audiences, nevermind having the storage system working against me.

akrymski超过 7 年前

Anybody tried Dropbox Paper?

Jedd超过 7 年前

I work with a large (multi-billion, multi-national) tech company that has a big problem with knowledge management.My job involves consulting to lots of customers in different industry sectors, and the one small, sad comfort is that almost no one does documentation management well.Currently if I want some specific tidbit of information I can consult: our knowledge base (bespoke), our collection of product PDF's, salesforce documentation repository, quickbase documentation repository, an aging wiki (twiki), private stash of documents created by colleagues, mailing lists (a subset of which are indexed and accessible from the wiki, otherwise you can only go back as long as you've been with the organisation, and hope you've been subscribed to all the right lists), sharepoint (meant to replace the wiki, but two years later, and no), our learning management system, yammer (seriously), bugzilla, our customer support forums ... or I think about who might know the answer and email them.My advice as a result of this:Even if you don't hire a librarian, at the very least appoint a curator -- ultimately you need someone who owns your documentation, and the design and management processes around it, and can encourage/force people to update it, continually reduce redundancy, improve quality, etc etc.Be wary of your current thinking " We'd like to have a single location to track both kinds of documentation ..." - specifically that there are only two kinds of documentation. Or indeed only n kinds of documentation.It's easy to fall into the 'let's build a new system to encompass the others' trap (insert obxkcd) and hard to fight it. If you do go down that path, ensure the content from old systems are fully migrated (3 years after it's been 'retired' our twiki is still the best place to go for some things). This is hard - it's rarely budgeted, and involves tedious and/or impossible work.I suspect it's impossible to have a single system that will manage all your institutional knowledge -- I know many people are working on solving this from both directions, but I don't believe there's anything suitable now.Whatever you choose it needs to have a low cost of entry for non-technical staff to update, while not frustrating your technical types. This is hard to find.In 2007 I set up DekiWiki (based on mediawiki, but since abandoned) for a medium-sized gov agency -- in 2013 when I caught up with that team I was surprised they were still running it. It was internal only, so they weren't so worried about lack of patches, and they hadn't found anything better in the interim.Out of that experience I'd suggest that whatever you do go with, make sure it's easy to extract your data, and that you maintain your own full copies of product documentation just in case the product is abandoned. Also - don't assume products won't be abandoned. MindTouch / Dekiwiki [1] was big in the mid 2000's.[1] <a href="https://en.wikipedia.org/wiki/MindTouch" rel="nofollow">https://en.wikipedia.org/wiki/MindTouch</a>