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
Ask HN: How does your team handle knowledge documentation?
81–90 of 93 posts
Re: Ask HN: How does your team handle knowledge documentation?
#82We 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!
Re: Ask HN: How does your team handle knowledge documentation?
#83Solution: 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.
I am afraid that the idea of hiring an expert for a specialized task goes against the trend of "full-stack developers". Imagine explaining why it is not necessary for the project to have a database expert, a back-end expert, or a web expert... but you definitely need a wiki-pages-organizing expert.
Perhaps that's a cue that "full stack developer" is just a cute buzzword for "jack of all trades, master of none".
Re: Ask HN: How does your team handle knowledge documentation?
#84Don't use confluence :( In every team I've been, confluence feels like an huge hole, we can never find what we are looking for...
This! As we use JIRA for ticketing we thought Confluence would be the best way. But like you said the problem is not that the information is not there. The problem is that the information is not findable and the search is in my opinion really poor.
To solve that problem we started with a "doc" directory in each repository holding multiple markdown files for each topic. That way all of our developers are able to find the information they need (even without an internet connection).
Re: Ask HN: How does your team handle knowledge documentation?
#85I 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 pa…
Do you mind to share what kind of X in “how to properly document X” pages you have?
I like that idea and would like to do similar!
Re: Ask HN: How does your team handle knowledge documentation?
#86Small 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 https://github.com/thomasswilliams/RigorousSearch-MediaWiki-...
Re: Ask HN: How does your team handle knowledge documentation?
#87Hey, I can recommend https://zenkit.com . 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.
Re: Ask HN: How does your team handle knowledge documentation?
#88I 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 pa…
Do you mind to share what kind of X in “how to properly document X” pages you have? I like that idea and would like to do similar!
I wouldn’t mind but our bureaucracy organ does :(. Whilst technically it is only moving the markdown files and CIconfig from our private gitlab to a public one, the bureaucracy involved with it prevents me from doing it today. I would have to pull a part of our source code which is under strict regulation, and I try to only start that process when I absolutely must do so (subsidiary projects mostly).
The contents are free to describe though. Essentially you would find a large number of pages on all language concepts for our main languages. So “how to document a method”, “how to document a property”, classes, namespaces, you get the idea.
Next, we have a very clear setup in our documentation pages. All pages and sections on pages have permalinks. The idea is that you can redirect people to the exact information they have to read. Every section always starts with three examples. The examples are different enough to be applicable to say 80% of the cases. This means most of time a developer does not need to read more than the examples, c/p one and adjust to his specific case.
After the example cases the different aspects are discussed that should be in. This includes rules like “use the 3rd person when writing descriptions”, “use present tense”, “start with active verb” but also “include minimally one example in the format above” and “never use the name of X in the description”. (I.e SetSomeCrypticThingOnlyWeUnderstand() // sets the cryptic thing After that (bullet/checklist) usually a paragraph describing the rationale for documenting like this as well as other information not captured in the examples or bullets.
Sometimes after this there is a section of “also consider” where we capture issues of the past. E.g “when documenting X that uses units, specify the units.”. I.e if you have a property Angle document it is degrees or radians. That same page would probably have a paragraph on should you name “Angle” or AngleInRadians or some info on avoiding ambiguous naming of properties.
I’d say the biggest game changers are the permalinks, good golden samples at the start of each section and in some cases bullet lists. The description paragraph is optional.
All our pages are markdown pages served on Gitlab Pages (on premise deployment) as static site built with MkDocs and Material theme (slightly customized) [1]. All pages include an “edit on gitlab” button so users can edit the pages in their browser without downloading any tooling. A CI setup will auto redeploy on commit/push. If clone the repo and you download MkDocs locally you can of course write with live reload etc on a local server (MkDocs serve).
O, and have a great search functionality and decent responsive website that is easy to read (good font, colors, syntax highlighting etc).
Re: Ask HN: How does your team handle knowledge documentation?
#89I 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, an…
I thought I didn't work at a large bank but you're making me doubt that, we must be in the same building.
Re: Ask HN: How does your team handle knowledge documentation?
#90For 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.