Documentation as code: Principles, workflow, and challenges | Hacker News Reader

Documentation as code: Principles, workflow, and challenges

tabnine.com

48 pointskiyanwang16 comments

Same as the other commenters, felt the article wasn't worth the time.

On documentation, it reminded me of the only aspect of JIRA that I really miss: the ease to link a ticket to a MR/commit, or even just mention the number in a comment.

That meant that on any code part, a quick look at the blame would get the ticket ID from the comment's prefix. Just paste the ID in a JIRA URL and voila: a full picture of the latest change that touched the code, what project/feature it was part of, the discussion on it if there was any, and potential the initial design documents linked from there.

Devs are lazy and so am I, having a single ID to stick anywhere to link to a context was so much easier that pasting notion links or having to write long MR descriptions.

I think people longing for more documentation would also be happy if our default tooling helped a lot more to link code to the external task management/discussion systems.

What are you using now instead of Jira that doesn't have the same/equivalent? That seems about as 'table stakes' as a title & description field to me, hardly unique to Jira.

I basically gave up on using ticket tracking for most projects.

It was just useless busywork, instead my team has a flat list of features/task to do for each releases, and we update it as part of the synchro meetings.

The big advantage is a ton of flexibility and having all the info we need in one place (e.g. we can inline release procedures with discrete tasks, have common info for a set of tasks etc.)

It requires more discipline (no reminders, burbdown, velocity etc.) but that works well enough with 3/4 people lines.

We do it in Notion, wo the urls are ugly and not really suitable for reference and different trams have a different management style.

Ah well I don't know about integrations/links from referencing the ID, but fwiw you can add an automatic numerical ID (including with a custom prefix) column to Notion tables.

> I basically gave up on using ticket tracking for most projects.

> It was just useless busywork, instead my team has a flat list of features/task to do for each releases

And are you hiring? (:sweat-smile: just kidding, sort of!)

Yes, Notion as gotten a ton of "project management" types of stuff, including an integrated calendar now that Cron is part of it.

The numerical ID feature looks nice. Notion tables aren't great, but it I guess it could work on task databases as well ? I'll try.

> are you hiring?

I look around every few years to see what would my options be, just in case. Asking how they manage their project feels more and more like the best reflection of their work environment, and very few have a coherent explaination of why they're using X method...

We're hiring, but it's a pretty niche japanese company, you probably already crossed it if you're in the space.

Sorry yes I did mean databases, not the sort of formatting-only tables which are a bit of an odd thing out in the way they have the child text areas (cells) which aren't themselves 'blocks' and only allow basic font/text styling.

That's a lot of words, and then nothing concrete.

I can counter that with concrete advice: make your own tooling because there isn't anything out there that is good. In iommi I wrote tooling to write tests with extra comments that are then projected into docs. The advantage is that the code examples are a part of the normal test suite. I also generate output .html files from examples that are then embedded as iframes into the documentation, which is a superior way of doing screenshots.

The article looks like it mostly for advertisment of their product. Quality for the article is definitely not the writer priority.

Yup. I'm in the techpubs systems business, and I tell everyone this: no matter how much you're spending on the tool stack, you will be wrenching on it, and probably quite a lot. So if you need to pay someone else to wrench, you have to keep that cost in mind; if you anticipate a metric buttload of wrenching, make sure to use something you can wrench yourself. You're going to run out of money reaaaaaaaal quick if you're paying a dozen PTC/Adobe consultants to come visit you once or twice a year. Not to mention when you need an emergency change yesterday - good luck getting an actual real English-speaking PTC rep to return a call this financial quarter.

Nothing irritates me quite as much as the usual "Open Source Isn't Cheap!" people. Mostly because of the cognitive dissonance: of course it's cheap, it's free. You're trying to gaslight the English dictionary. Cheap doesn't mean cost over time, it means cost right now. A 1998 Kia Sedona is cheap. Now, does it cost a whole bunch? Well, maybe it will, and maybe it won't[1], but that doesn't make it not cheap. Goddammit.

[1] Although, with the Sedona, probably it will. I'm more of a "grab a farted up old Lexus or Infiniti" kind of guy.

Here is our approach: From Markdown to a Docusaurus Website via GitHub, gh Actions, and gh pages

https://baky0905.github.io/personal-website/blog/2021/04/02/...

Long read for an advert. The value of docs is the "why" behind a design and A"I" does not capture this. To be completely fair, most devs are super bad at this, too. Tbh I would not pay for an automat that clutters my documents with ease.

I wrote a custom tool that “runs” tutorials and embeds the output of commands in the resulting doc. It also acts as a test as each command run is checked for non-zero exit.

It supports some neat features like webpage manipulation and screenshots. Check it out https://github.com/zombocom/rundoc

I prefer collocating docs with inplementation, but it requires a designed architecture to support. Example: https://github.com/xixixao/recomputer

Meh article but it raises an interesting question: How do you test documentation? The best (and maybe the only real) test is be for someone unfamiliar to try it and manage to do what it explains. You can't rerun that test without finding a new person.

That’s legitimately one valid way to test docs. The hard part is finding the target audience. 10 years ago HN was alite with tips like “offer people a $25 gift card to test your X” instead of the current LLM craze. Good design needs feedback.

Also I linked in another thread, it’s possible to run and test some types of documentation. It won’t guarantee it is good for the end user but it will at least guarantee it’s doesn’t error.

I always make going through our docs a part of new-hire onboarding. They learn the product, and you learn what in your docs is so confusing that a person who you hired for their supposed ability to help you MAKE your product, can't even figure out ABOUT your product.

But also, I did work on a project once where a test would scrape code snippets from documentation and make sure they still worked as expected. It's bad enough to break compatibility in your CLI, etc. but sometimes you need to do it. It's really bad when you have tutorials, recipes, etc. and they bit rot.

Reply on news.ycombinator.com