3 ms·

Documentation as code: Principles, workflow, and challenges

48 points by kiyanwang 3y ago

jeffreygoesto 3y ago
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.
xixixao 3y ago
I prefer collocating docs with inplementation, but it requires a designed architecture to support. Example: https://github.com/xixixao/recomputer https://github.com/xixixao/recomputer
boxed 3y ago
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.
- NewsaHackO 3y ago
  The article looks like it mostly for advertisment of their product. Quality for the article is definitely not the writer priority.
- MilStdJunkie 3y ago
  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.
makeitdouble 3y ago
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.
- OJFord 3y ago
  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.
  - makeitdouble 3y ago
    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.
    - OJFord 3y ago
      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!)
west0n 3y ago
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/docusaurus/ https://baky0905.github.io/personal-website/blog/2021/04/02/...
Jeff_Brown 3y ago
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.
- schneems 3y ago
  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.
- macksd 3y ago
  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.
schneems 3y ago
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 https://github.com/zombocom/rundoc

48 points by kiyanwang 3y ago

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.

xixixao 3y ago

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

boxed 3y ago

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.

NewsaHackO 3y ago
The article looks like it mostly for advertisment of their product. Quality for the article is definitely not the writer priority.
MilStdJunkie 3y ago
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.

makeitdouble 3y ago

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.

OJFord 3y ago
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.
- makeitdouble 3y ago
  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.
  - OJFord 3y ago
    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!)

west0n 3y ago

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/docusaurus/ https://baky0905.github.io/personal-website/blog/2021/04/02/...

Jeff_Brown 3y ago

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.

schneems 3y ago
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.
macksd 3y ago
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.

schneems 3y ago

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 https://github.com/zombocom/rundoc