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

The Surprising Power of Documentation

vadimkravcenko.com

Post reply on HN
Print view View original

41–50 of 153 posts

Re: The Surprising Power of Documentation

#41

Post by bambax »

Klaster_1 wrote: post #16
bambax wrote: post #10

We're currently trying to document an existing large Angular application and it's daunting. We wrote some meta-code to list all possible routes and attach components to routes (we were hoping Compodoc would help, but it doesn't work well anymore). We have over 700 routes (screens), 1200+ components and 500+ different service calls that query APIs in the back end. If we only look at routes and hope to spend, on averag…

As a fellow Angular developer at a similar state of affairs, I am curious as to what problems you think documentation would solve, how you plan to maintain it after more "Jira tickets" layer up and what's your general strategy.

We hope it will save time when assessing bugs and describing new features, by providing a base reference of what the code currently does.

We intend to have designers update the doc when describing a change request, and the devs also update the doc afterwards.

We're not sure any of this is going to work; in the life of the project there has been at least two major documentation efforts, that failed because they were eventually abandoned (not maintained).

Some are still hoping there's some kind of magic bullet that would let us automate everything... and I'm not immune to this myself.

Re: The Surprising Power of Documentation

#42

Post by Karrot_Kream »

cjfd wrote: post #39
atoav wrote: post #31

Earlier quoted context omitted.

I really like the way documentation works in Rust: You basically write markdown in a special type of comment over the module, function, datatype or method you wanna document and then you can convert that into documentation automatically. Even better: if you have examples in code blocks in these docstrings per default they get tested as well, so if you don't update them, the tests will fail and you will notice. In my…

I don't have experience with this in Rust but have come to passionately hate this kind of documentation in other language. I think all of pydoc, javadoc and, doxygen are all garbage. If one could apply them sensibly it would not be so much of a problem but then you have documentation nazis who force you to document every method and every parameter. This leads to hightly enlightening prose documentation that the get_h…

Yeah this is why I love literate programming. Being able to read a program with "narration" is so much nicer than just reading documentation piecemeal. Maintaining literate programs though is a quite difficult because you have to figure out where new code or changes fit in the overall narrative. I have a scraper I wrote in literate style and I only have to change it yearly. Each year I forget what I wrote and then I reread the program and make the necessary changes.

Re: The Surprising Power of Documentation

#43

Post by marginalia_nu »

Problem with documentation is that there are a lot of uses for documentation. It can be a reference, it can describe the architecture, it can do many things. Probably a good idea to figure out what the intent is first to find a good form.

Some of my stuff is pretty sprawling, I've started integrating the documentation with the code and basically use readme.md's littered in the code as sign-posts to let you navigate it more quickly. The intent of that documentation is pretty clear, and the shape follows logically.

e.g. https://github.com/MarginaliaSearch/MarginaliaSearch/tree/ma...

Re: The Surprising Power of Documentation

#44

Post by bayindirh »

Karrot_Kream wrote: post #42
cjfd wrote: post #39

Earlier quoted context omitted.

I don't have experience with this in Rust but have come to passionately hate this kind of documentation in other language. I think all of pydoc, javadoc and, doxygen are all garbage. If one could apply them sensibly it would not be so much of a problem but then you have documentation nazis who force you to document every method and every parameter. This leads to hightly enlightening prose documentation that the get_h…

Yeah this is why I love literate programming. Being able to read a program with "narration" is so much nicer than just reading documentation piecemeal. Maintaining literate programs though is a quite difficult because you have to figure out where new code or changes fit in the overall narrative. I have a scraper I wrote in literate style and I only have to change it yearly. Each year I forget what I wrote and then I…

Literate programming is great until your code base becomes unwieldy. Then you need a README.md file which acts like a pointer to the correct entry points.

Then as the code grows, you need to document the architecture, add small gotchas, etc.

At the end of the day, documentation wins.

Re: The Surprising Power of Documentation

#45

Post by hahnbee »

dschuetz wrote: post #32

While I agree that docu is important I've seen my share of garbage poured into wikis and presented as the single source of truth. It takes a lot of time and effort to make docu meaningful and useful with the outlook that it's ignored and overlooked anyways. Quality documentation is expensive, and, if one invests heavily into it there must be a clear workflow path that makes following and reviewing docu mandatory. Doc…

stale documentation is worse than no documentation

Re: The Surprising Power of Documentation

#47

Post by c00lio »

cjfd wrote: post #39
atoav wrote: post #31

Earlier quoted context omitted.

I really like the way documentation works in Rust: You basically write markdown in a special type of comment over the module, function, datatype or method you wanna document and then you can convert that into documentation automatically. Even better: if you have examples in code blocks in these docstrings per default they get tested as well, so if you don't update them, the tests will fail and you will notice. In my…

I don't have experience with this in Rust but have come to passionately hate this kind of documentation in other language. I think all of pydoc, javadoc and, doxygen are all garbage. If one could apply them sensibly it would not be so much of a problem but then you have documentation nazis who force you to document every method and every parameter. This leads to hightly enlightening prose documentation that the get_h…

I am a documentation nazi. I hate it when people skip over documentation because something is obvious or trivial to them. Stuff isn't obvious or trivial to people who have to use your code.

get_height gets which height, outer or inner? Are there error values, e.g. 0 as "don't know any height"? Does it have side effects? Is it a stable and reliable part of the API or bound to change soon? Is it thread safe? Will it change any of its parameters? Who deallocates the return value? Do you need to hold a lock somwhere?

Of course it might be a good idea to group together get_height, get_width, get_diagonal and get_depth if the above is all the same for those. But having no documentation just because you think it is trivial that get_height gets some height from somewhere just means that you are sloppy and didn't think of all of the above. So your code shouldn't be touched with a 10-foot-pole imho.

My solution, which I personally hate but know of no alternative to, is a documentation template for each function asking the above questions (depending on runtime and language of course) that I give people to fill in. Until they learn...

Re: The Surprising Power of Documentation

#48

Post by hitchstory »

atoav wrote: post #31
franciscop wrote: post #6

This is too biased for-docs IMHO*. I do agree with many points, documentation IS amazing, and you are very likely under-documenting things in your company. But documentation is not cheap to create, and specially it's not cheap to maintain. If you are not writing enough yes, sure, that's probably a great investment, but start bit by bit. I've worked in multiple* companies where the problem was too much documentation,…

I really like the way documentation works in Rust: You basically write markdown in a special type of comment over the module, function, datatype or method you wanna document and then you can convert that into documentation automatically. Even better: if you have examples in code blocks in these docstrings per default they get tested as well, so if you don't update them, the tests will fail and you will notice. In my…

I built a testing library on top of pytest based upon the idea of doing this mapping at an application level instead of a method/function/class level.

If you write tests in a strongly typed, non-turing complete markup (in this case, StrictYAML), you can then use it with a template and test artefacts (e.g. app screenshots) to generate readable how-to/tutorial docs which are guaranteed to stay up to date.

https://github.com/hitchdev/hitchstory

This isn't a new idea, but I find that people are often skeptical because there's a history of people getting their fingers burned by Gherkin's language design or YAML's weak typing (both of which are completely valid).

Re: The Surprising Power of Documentation

#49

Post by magicalhippo »

bambax wrote: post #10

We're currently trying to document an existing large Angular application and it's daunting. We wrote some meta-code to list all possible routes and attach components to routes (we were hoping Compodoc would help, but it doesn't work well anymore). We have over 700 routes (screens), 1200+ components and 500+ different service calls that query APIs in the back end. If we only look at routes and hope to spend, on averag…

We're in a similarish situation. We decided to accept spending a bit of time on the documentation every time some JIRA ticket requires us to work on an undocumented section of code.

Not everything requires a lot of documentation, we have a lot of essentially glorified input dialogs, but we do try to write down what it is, and especially any logic and config settings that affect that logic.

One thing I've used before with success and which we've also introduced was two new fields in JIRA, "requires documentation update" and "documentation updated", to aid not forgetting to update documentation when adding or changing code.

Re: The Surprising Power of Documentation

#50

Post by hahnbee »

franciscop wrote: post #6

This is too biased for-docs IMHO*. I do agree with many points, documentation IS amazing, and you are very likely under-documenting things in your company. But documentation is not cheap to create, and specially it's not cheap to maintain. If you are not writing enough yes, sure, that's probably a great investment, but start bit by bit. I've worked in multiple* companies where the problem was too much documentation,…

I'm the CTO of Mintlify - we help other startups create their developer-facing documentation. We've been working in the documentation space for a little over a year now and I spend a lot of time thinking about documentation. I completely agree here.

Documentation is such a hard problem to "solve" if you're a fast-moving startup. You need a mixture of creating a documentation-first culture and acknowledging that documentation is difficult to maintain. Ultimately you end up creating processes to help people document their intent, decisions and the mission critical information.

There is also such a large range of types of documentation - varying scale from internal to external and technical to non-technical.

We started by creating https://writer.mintlify.com/ which really resonated with developers because it made it easier to write documentation, but it only helped generate documentation that was highly technical and close to the code. We decided to stay in the documentation space but try another vector and so now we're taking a crack at public-facing documentation - which in my opinion is a different can of worms than internal documentation. However as I'm building and growing my startup and I find myself continuously playing whack-a-mole and I definitely hope that we can build the foundation and expand to make it easier to maintain all different types of documentation.

Post reply on HN