Hacker News Reader

Comment by bambax | Hacker News Reader

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 average, one day per screen, that's 700+ days of writing docs, which is a considerable amount of work.

There's no existing documentation, save for 30,000+ JIRA tickets over a 5-year period, that describe various bug fixes and change requests. But those tickets are just floating in the ether and are not formally attached to any specific component, let alone route.

I was hoping AI would help but I can't seem to find anything relevant.

What would you do?

View on HN

I would go from the most pressing problem, apply the Pareto principle to solve it, and repeat until reasonably happy. What is the biggest actual pain that the current lack of docs causes? I do not yet know the answer (feel free to share), but there is a good chance that the problem does not actually require a formal description of every screen one by one. You may be trying to create reference docs where higher level and more abstract documentation is warranted.

What would you do?

Accept that it's a big job and just get on with it. Sometimes we just have to do hard things. Putting it off or looking for a shortcut doesn't always work.

I'd also spend a couple of months seeing how much of the documentation production I can automate though. That's a small investment in a 700 day project.

Yeah. There's this quote I love:

> If you have a mountain of shit to move, how much time should you spend looking for a bigger shovel? There's no obviously correct answer - it must depend on the size of the mountain, the availability of large shovels, how quickly you have to move it etc. But the answer absolutely cannot be 100% of your time. At some point you have to shovel some shit.

From https://www.scattered-thoughts.net/writing/things-unlearned/

The corollary is also important. If you are writing code you should want it to solve a problem, and for it to be the chosen solution regularly. Make sure people with the problem you are solving know that your solution solves their problem, and how it solves their problem. That's the point of documentation.

Hire a couple of technical writers with experience and let them get on with it, and then make your devs document every new feature and change. Nothing passes code review unless it is accompanied by updated documentation. Getting your devs to document the existing codebase when you've inherited a shitshow like this will pull them away from their jobs for too long.

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.

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.

> If we only look at routes and hope to spend, on average, one day per screen, that's 700+ days of writing docs, which is a considerable amount of work.

It sounds like you're thinking about the really boring kind of documentation. The kind that no one wants to read and certainly no one wants to write.

In some approaches, the 4 types of documentation are tutorials, how-to guides, technical reference and explanation.

Any per-screen documentation is not tutorial, how-to or explanation. Perhaps it might be technical reference.

The first question then is why are you working on technical reference? Would you get more bang for the buck writing how-to guides?

We have docs and videos and whatnot, that describe how to use the application in order to accomplish a given task, in general terms (find some entry in the menu, go there, click that button).

What we do not have is something that describes exactly what the system is supposed to do, so that when one stumbles upon an unexpected behavior, they don't know if it's a bug or if it was intended that way (it could be either, depending on old requirements that weren't properly written down).

do you have usage analytics or ticket token analytics? i would document the most commonly accessed/used stuff first.

and make sure this is at least one person's actual full-time job. chances are you'll have to hire specifically for this role because nobody wants to be bait-and-switched into this job, but there are actual professionals that do this for a living.

Reply on news.ycombinator.com