Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

The case for continuous documentation

virtuallifestyle.nl

Post reply on HN
Print view View original

31–40 of 71 posts

Re: The case for continuous documentation

#31

Post by aidos »

Noumenon72 wrote: post #9
simonw wrote: post #4

I'm adamant that the documentation for a project should live in the same repository as the code itself. This is crucial for a number of reasons: 1. If the docs are in the same repo, a commit that changes the code can update the relevant documentation (in addition to the tests) as part of the same unit of work 2. This means it can be enforced during code review: if a developer forgets to update the docs they can be re…

How do you read the in-repo documentation? Search for all files named readme.md? I have never learned about a library from documentation scattered about the repo. There's the readme at the root, and everything else is on a web page, which is a better way to organize and browse documentation.

In the PostgreSQL codebase they have readmes scattered about and it’s great to jump into some subfolder and get the details you need in the right context.

Re: The case for continuous documentation

#32

Post by 0xbadcafebee »

pram wrote: post #16

Documentation is great and all, but no one ever talks about when theres too much. Maybe because it's rare? At big companies I've seen "architects" churn out page after page of diagrams, design docs, runbooks, checklists, descriptions, etc. There is so much information that it becomes practically useless in aggregate, because no one is reasonably going to read it all. I'm not going to pretend that I have the patience…

There is no such thing as too much documentation. There is out of date documentation, inaccessible documentation, unindexed documentation, poor documentation, redundant documentation, etc... But what you described is amazingly valuable. Just because it's not valuable to you, right now, doesn't mean there's too much of it.

Re: The case for continuous documentation

#33

Post by cryptica »

yosefk wrote: post #3

If you essentially have one live version of your program, like you do when it runs on your servers, coupled documentation is probably a good idea. If you have multiple active versions, like you often do with software released to run on someone else's machines, coupled documentation "works," but has a big downside. Namely, it prompts people to "refactor mercilessly"/change everything all the time, together with the do…

I think this argument makes perfect sense. Personally I don't like in-line documentation. It's mostly popular among people who depend on bulky proprietary IDEs. I hate all these approaches which try to trick people into using proprietary tech.

I enjoy reading a nice documentation website maintained by the open source organization; it also gives me a touch-point with the organization which created the library. I also agree with your nuanced argument concerning incentives. Arguments related to incentives are almost always discarded by managers but they are very important.

I do think decoupling the documentation encourages people to think about documentation more carefully as a distinct and important activity. I find that in-line documentation tends to be neglected; as a developer, when you're in the middle of coding an important feature which requires your full attention, you don't want to be distracted with updating the comments all the time because it breaks your train of thought. Usually developers tell themselves that they will do it later and they often forget. Comments are often neglected in the PR review process too.

There is no way around it, you need to set aside some time to write or update the documentation as a distinct activity. There is a time for coding and there is a time for explaining.

Re: The case for continuous documentation

#34

Post by 0xbadcafebee »

There are still unsolved problems with documentation that I'd like to find solutions for.

Everything can be made into code, but at a certain point it's just so complicated to do that you're spending more time and money automating your docs than your applications. So until we have solutions for all that, you will have to maintain some docs manually.

For those manual docs, how do you keep them fresh? I've thought of automatically sending an email to warn that in 30 days the document would be deleted unless someone updated it, but even if people agreed to such a system, they could just update some punctuation and it would remain stale. Even blank pages, people seem to want to keep around rather than fix.

How do you navigate your docs? Search engines actually suck for the most part. Search is a hard problem to solve, and a home rolled search will usually net terrible results. On the other hand, most people don't have the time to maintain a governance structure for their docs, much less an enforcement mechanism, so the docs invariably become terribly organized.

People also seem to need training to learn how to write good docs. I know there are some trendy pages being passed around about some kind of "golden framework for docs" but they don't explain how to write them either. I know how to write docs, but I feel like I'd need to write a whole book to get it across. One thing I found really useful was Atlassian's newer Confluence page templates, which come well organized and primed with examples of how to write the docs.

As a philosophy, I really, really love GitLab's Handbook First model. Their handbook is incredibly detailed and covers pretty much their whole organization, and is fairly easy to update. I feel like this one one of the magical missing links in getting more documentation for the important things that aren't code.

Re: The case for continuous documentation

#35

Post by brox »

klohto wrote: post #11
Noumenon72 wrote: post #9

Earlier quoted context omitted.

How do you read the in-repo documentation? Search for all files named readme.md? I have never learned about a library from documentation scattered about the repo. There's the readme at the root, and everything else is on a web page, which is a better way to organize and browse documentation.

Static site generated from the repo. Can be hosted locally or online. Github pages are usually leveraged for this usecase

If using Django there are tools like django-docs (https://django-docs.readthedocs.io/en/latest/) and the recently released django-sphinx-view (https://noumenal.es/django-sphinx-view/).

Re: The case for continuous documentation

#36

Post by iib »

cryptica wrote: post #33
yosefk wrote: post #3

If you essentially have one live version of your program, like you do when it runs on your servers, coupled documentation is probably a good idea. If you have multiple active versions, like you often do with software released to run on someone else's machines, coupled documentation "works," but has a big downside. Namely, it prompts people to "refactor mercilessly"/change everything all the time, together with the do…

I think this argument makes perfect sense. Personally I don't like in-line documentation. It's mostly popular among people who depend on bulky proprietary IDEs. I hate all these approaches which try to trick people into using proprietary tech. I enjoy reading a nice documentation website maintained by the open source organization; it also gives me a touch-point with the organization which created the library. I also…

Can you not just not write the documentation, even if it resides in the same repository, and then later make a commit to update it, as a separate task?

Re: The case for continuous documentation

#39

Post by remoquete »

The article seems to skim over the complexities of docs workflows and the role of docs. In fact, docs are nowhere to be found throughout the article. What are those “docs” that the OP is talking about?

Perhaps it’d be fair to rename that article “The Case for Continuous READMEs”.

Re: The case for continuous documentation

#40

Post by Zababa »

Noumenon72 wrote: post #9
simonw wrote: post #4

I'm adamant that the documentation for a project should live in the same repository as the code itself. This is crucial for a number of reasons: 1. If the docs are in the same repo, a commit that changes the code can update the relevant documentation (in addition to the tests) as part of the same unit of work 2. This means it can be enforced during code review: if a developer forgets to update the docs they can be re…

How do you read the in-repo documentation? Search for all files named readme.md? I have never learned about a library from documentation scattered about the repo. There's the readme at the root, and everything else is on a web page, which is a better way to organize and browse documentation.

The webpage can be generated from markdown files which can be in the repo.
Post reply on HN