Live data from Hacker News

Ask HN: How To: Internal Documentation?

news.ycombinator.com

41–50 of 53 posts

Re: Ask HN: How To: Internal Documentation?

#41
post #21

Internal documentation is nice, but really quite worthless for primarily three reasons: 1. At most one person is willing to create it 2. Nobody is willing to update it 3. Nobody is going to read it

Correctamundo! And here's 15 more... https://www.komment.ai/blog/18-good-reasons-why-developers-h...

You have to wonder how privileged developers are. Documentation and communication are essential for the job yet nothing much happens if it’s not done properly. („Programmers are bad writers.“ is an valid excuse)

Compare this to a painter who refuses to wash out their brushes - that’s „uninspiring“ work, so not going to do it. No one would excuse a painter by saying: he can’t wash out brushes.

Writing and documenting are skills that can be learnt, there isn’t anything that makes you a born „writer“ or „developer“ - one can easily enough do both.

Re: Ask HN: How To: Internal Documentation?

#42
post #40
post #28

Most companies don’t have a problem with too little documentation. Instead, the documentation is hard to find when needed. I’m a documentarian and this is one of my favorite topics. My go to is creating a wiki for the team. The wiki is organized into hubs. There is a hub for each team. There is a hub for each topic such as security, new employee onboarding, etc. There might be a hub for each bigger project. A hub con…

How do you handle the discovery/relevance issue in a documentation base that is already several years old?

I like to use the strangler fig pattern. This concept is used to build a new version of a system alongside an existing legacy system, but I think the idea also works for building a new documentation system alongside a heap of old unorganized info.

Start by building a structure with some empty templates, a d a few instructional examples. Then ask the team to bring over information into the new system whenever they find something useful in the old system. Minimally, ask them to drop a link in a relevant hub or two. Even better if they spend 5 minutes copying it over to the new system, and adding a note with a link to the new version in the old system.

Over time the new documentation system will strangle the old one. Hence the name.

Team participation is a must. This will not work if it is a one man effort. Have managers push and encourage people to participate in the documentation effort.

Side note: the strangler gig is a fazcinating plant.

Re: Ask HN: How To: Internal Documentation?

#43
post #6

Docs should be as close to source code as possible, ideally in the same repo so they can be updated and reviewed in the same PR as the source changes themselves. Markdown works fine. For docs that don’t relate to source, just have a repo for general docs. Not only is Confluence absolute crap, tech docs in it rot because it’s a separate system developers don’t want to use. Similar story for MediaWiki.

I agree but aren’t there docs that might be needed by non-technical people as well. The general doc repo might contain “bureaucratic” information (what I mean is who owns the application, what is the security concept, what other apps does it communicate with and who are their owners, how does it get audited, etc.).

Of course we can set up an export to a static website from the repo, but how would a non-technical person edit it, say if the owner or audit process changes?

Re: Ask HN: How To: Internal Documentation?

#46
This is a passion and pet peeve of mine. Here are my takeaways:

1) Technical documentation should be coupled with code, so devs will update it as services change (especially in a large or microservice oriented company), and that documentation is pulled into the general purpose system (read: non-tech, mgmt) This also vastly helps with versioning and finding old info (confluence versioning sucks)

2) Diagrams should be diagrams as code, for the same reasons, especially the versioning part. Can you tell me what your infra looked like exactly 3 iterations ago? This helps in problem solving when you've had long-tail undiscovered complications.

3) Make it part of product ownership, KPIs and OKRs. Product managers are the literal worst at this, and will try to push stuff to prod without it otherwise. Coming from the Ops end of things, I can't tell you how infuriating it is to get told "this product is going to prod next week" and when I look there are no ops docs!

4) Management really has to support these efforts, up to hiring someone just to manage documentation. Not just that, but the culture. One thing I've seen repeatedly, especially in high-speed/low-drag places full of PHDs and heavy engineers, is using no docs as a way to judge prod teams. I've made much progress explaining in detail why when an ops engineer is at the tailend of a shift and a sev1 happens, they don't have time or the right mental clarity to go read the code to understand your bullshit!

5) All that said, the biggest division is between the non-tech and tech teams. Do not forget to give non-techs good usability and visiblity into these systems, or management will eventually stop supporting it.

6) Some people will have a passion for documentation, despite being in teams that might not be related to it. Utilize them, and reward them!

Bonus) Include lack of documentation in your after-actions/post-mortems, to keep it relevant to uppers in a concrete way.

Re: Ask HN: How To: Internal Documentation?

#47
For all the getting started and basic process documentation, you can keep it up to date by asking new hires to fix things, or update things based on their questions.

The biggest problem at larger firms is always dealing with other teams. It's inevitable that building and running your app will involve them, and their documentation may be lacking or non-existent. While you can't fix that, you can at least create a list of contacts.

Re: Ask HN: How To: Internal Documentation?

#48
post #6

Docs should be as close to source code as possible, ideally in the same repo so they can be updated and reviewed in the same PR as the source changes themselves. Markdown works fine. For docs that don’t relate to source, just have a repo for general docs. Not only is Confluence absolute crap, tech docs in it rot because it’s a separate system developers don’t want to use. Similar story for MediaWiki.

I would kill for code-adjacent docs right now.

We're a documentation-heavy org and having to open Confluence, find the right root page, drill down to where I need to be, and deal with ~1s page loads drives me nuts.

Re: Ask HN: How To: Internal Documentation?

#49
I think the problem with documentation is that most workers feel it's the lowest grunt task, training your replacements and not 'doing'. When in reality, you're helping onboard the next wave of people. And the best part is they don't necessarily need your time, just your docs.

I've on many occasions have been a part of detailing documents and creating them for the purpose of how-tos, I always felt a sense of accomplishment when being able to help new people into the team especially if it was something I struggled with.

A trusted colleague and I were talking recently about documentation and I was saying this much, they said it's the work that the lowest person at the company would do and I should stop viewing it as such a high level. I still enjoy documenting process but now I don't want to do it due to the fact that it is seen this way.

Re: Ask HN: How To: Internal Documentation?

#50
post #6

Docs should be as close to source code as possible, ideally in the same repo so they can be updated and reviewed in the same PR as the source changes themselves. Markdown works fine. For docs that don’t relate to source, just have a repo for general docs. Not only is Confluence absolute crap, tech docs in it rot because it’s a separate system developers don’t want to use. Similar story for MediaWiki.

I agree but aren’t there docs that might be needed by non-technical people as well. The general doc repo might contain “bureaucratic” information (what I mean is who owns the application, what is the security concept, what other apps does it communicate with and who are their owners, how does it get audited, etc.). Of course we can set up an export to a static website from the repo, but how would a non-technical pers…

Certain static sites can hook up into a WYSIWYG CMS backend, although I'm not sure how nice they play with version control.
Post reply on HN