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

61–70 of 71 posts

Re: The case for continuous documentation

#61

Post by zie »

simonw wrote: post #46
CraigJPerry wrote: post #5

If it's technical docs for developers, you'll get more bang for your buck by making executable documentation first - tests, deployment automation, build automation. Make it so that to do 1 logical action then there's only 1 step needed. How do i build this? Run the build command. How do i test this? Run the test command. How do i run only the unit tests? Run the unit test command. How do i start this locally? Run the…

GitHub have a pattern for this called "scripts to rule them all" - https://github.com/github/scripts-to-rule-them-all - I've not fully adopted it yet but I probably should, it looks very well thought-out.

We just abuse Make, so make test, make bootstrap, etc.

Re: The case for continuous documentation

#62

Post by euroderf »

papito wrote: post #23

In the least - your repo should be the main gateway to a proper WIKI. The problem with decoupled documentation is that it's the proverbial tree in a forest - no one knows it's there when it "drops". Docs are like code - the less your write of it, the less you have to maintain. Documentation should be treated as inherently evil. The only worse thing than no documentation is documentation that is not maintained and out…

Yes, "Wrong documentation is worse than no documentation."

Re: The case for continuous documentation

#63

Post by forgotmypw17 »

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.

Write the documentation as text files.

Include hashtags for topics, e.g. #authentication, #language, or #netscape.

Use the text file indexing and management system to browse and update the documentation.

Re: The case for continuous documentation

#64

Post by forgotmypw17 »

a1369209993 wrote: post #55
zelphirkalt wrote: post #54

Earlier quoted context omitted.

I see. Sometimes it seems, that there is some kind of animosity towards any non-markdown format, as if markdown was the one and only. Ha, so far from it ... But everything else must be eradicated with some kind of hostility, it seems. The people exhibiting this kind of behavior often do not know other formats well, nor have they bothered to use another format for a while to find out about what it can express. It is a…

> Sometimes it seems, that there is some kind of animosity towards any non-markdown format Can't speak for anyone else, but for my part there is animosity towards any format , period. Documentation should be plain ASCII - or, when strictly necessary[0], UTF-8 - text, and readable as such with only human-generated ad hod syntax such as *emphasis* or +------------------+ | ascii-art tables | +---+--------------+ | + |…

I agree wholeheartedly.

The most annoying thing about Markdown is that most of the time (90%, I'd say) it's added some kind of formatting, I was not trying to format anything at all.

Re: The case for continuous documentation

#65

Post by chupchap »

simonw wrote: post #59
chupchap wrote: post #58

Earlier quoted context omitted.

> 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: I have a small disagreement on that. I always feel documentation should be outside of code as it might need to be reviewed by people who do not have access access to the code base. Then there are also the "Why are we doing this" part of documentation that is difficult to m…

The docs may live in the repo but they should definitely be published somewhere that non-GitHub users in the organization can view. The higher level strategic stuff can absolutely live elsewhere - in my experience Google Docs or some kind of company-wide wiki often come into play here.

I was thinking more of an enterprise situation where multiple systems might be working together as part of a process. The code for each system might be in different repos in which case the documentation would also be broken. In such a context having the unit level documentation in the repo makes sense, but the overarching process documentation that is constantly evolving and referenced by multiple teams cannot be part of this repo.

Re: The case for continuous documentation

#66

Post by a1369209993 »

a1369209993 wrote: post #55
zelphirkalt wrote: post #54

Earlier quoted context omitted.

I see. Sometimes it seems, that there is some kind of animosity towards any non-markdown format, as if markdown was the one and only. Ha, so far from it ... But everything else must be eradicated with some kind of hostility, it seems. The people exhibiting this kind of behavior often do not know other formats well, nor have they bothered to use another format for a while to find out about what it can express. It is a…

> Sometimes it seems, that there is some kind of animosity towards any non-markdown format Can't speak for anyone else, but for my part there is animosity towards any format , period. Documentation should be plain ASCII - or, when strictly necessary[0], UTF-8 - text, and readable as such with only human-generated ad hod syntax such as *emphasis* or +------------------+ | ascii-art tables | +---+--------------+ | + |…

> when strictly necessary[0]

Missed this and too late to edit.

0: Which historically meant "not stupid-quotes", with a addendum for stupid-dashes, stupid-ellipses, etc, but now also includes "not emoji".

Re: The case for continuous documentation

#67

Post by navotgil »

dllthomas wrote: post #43
deeblering4 wrote: post #37

Oh cool, so books and websites in general are “bad” now.

Not, by this metric, if they live in the same repo as the code. When they don't, they have the same problem as any strongly coupled systems maintained across multiple repos, or you are paying the cost of keeping the two uncoupled.

This is why projects with micro service architecture are best saved in a mono repo

Re: The case for continuous documentation

#69

Post by zelphirkalt »

a1369209993 wrote: post #55
zelphirkalt wrote: post #54

Earlier quoted context omitted.

I see. Sometimes it seems, that there is some kind of animosity towards any non-markdown format, as if markdown was the one and only. Ha, so far from it ... But everything else must be eradicated with some kind of hostility, it seems. The people exhibiting this kind of behavior often do not know other formats well, nor have they bothered to use another format for a while to find out about what it can express. It is a…

> Sometimes it seems, that there is some kind of animosity towards any non-markdown format Can't speak for anyone else, but for my part there is animosity towards any format , period. Documentation should be plain ASCII - or, when strictly necessary[0], UTF-8 - text, and readable as such with only human-generated ad hod syntax such as *emphasis* or +------------------+ | ascii-art tables | +---+--------------+ | + |…

That is an interesting approach as well. What I see as advantages are: that there is no need for a specification and no need for it to be rendered, as one is to view it as plain text.

What I see as disadvantages are: It is not possible to render it properly or have support for it beyond showing plain text. Many users might write things different from each other, which might affect how easily a reader picks up what each document's style or conventions are.

Re: The case for continuous documentation

#70

Post by a1369209993 »

zelphirkalt wrote: post #69
a1369209993 wrote: post #55

Earlier quoted context omitted.

> Sometimes it seems, that there is some kind of animosity towards any non-markdown format Can't speak for anyone else, but for my part there is animosity towards any format , period. Documentation should be plain ASCII - or, when strictly necessary[0], UTF-8 - text, and readable as such with only human-generated ad hod syntax such as *emphasis* or +------------------+ | ascii-art tables | +---+--------------+ | + |…

That is an interesting approach as well. What I see as advantages are: that there is no need for a specification and no need for it to be rendered, as one is to view it as plain text. What I see as disadvantages are: It is not possible to render it properly or have support for it beyond showing plain text. Many users might write things different from each other, which might affect how easily a reader picks up what ea…

> It is not possible to render it properly or have support for it beyond showing plain text.

Sure you can, and indeed that's what markdown was originally supposed to do (at least as it was first described to me). The catch is that you have to treat the plain text as the authoritative version: you do not edit the plain text in order to produce changes in the rendered document; you edit the plain text for it's own sake, without considering the effect on the rendered version, and the rendered version is derived from that.

Post reply on HN