4 ms·

How to add documentation to your product life cycle

110 points by taubek 3y ago

rapnie 3y ago
The observation that hardcore True Developers™ absolutely hate documentation chores is maybe reflected in low upvote and comment count on this thread. But seriously, this is a good listing of pros and cons, and it is a pity not more experiences are shared. Commercial products usually pay good attention to the docs, but esp. FOSS projects are often severely under-documented. Model may be different here as often the single dev is the documenter too (and hates that chore). I tried Readme Driven Development [0] for a while, but found it still resource-intensive to keep things up-to-date. For single devs, small teams the Diátaxis framework [1] is helpful to organize and makes the task a bit lighter. [0] https://tom.preston-werner.com/2010/08/23/readme-driven-development.html https://tom.preston-werner.com/2010/08/23/readme-driven-deve... [1] https://diataxis.fr/ https://diataxis.fr/
- verve_rat 3y ago
  Everyone wants good documentation, no one wants to pay for a technical writer.
  - euroderf 3y ago
    "I mean c'mon, how difficult can it be to write technically ?"
- hitchstory 3y ago
  I started doing documentation driven development a while back (with FOSS code) I wrote and I realized at some point that my tests and my how to docs were doing the same thing - one was just an easier to read version of the other. Moreover, when one went out of date so did the other. So, I tied them together - I wrote integration tests such that with a jinja2 template I could autogenerate readable markdown how-to docs from the tests and their artefacts. Setting that up led me to the realization that writing docs isn't actually tedious at all. It's the writing things down 3 times (spec, test & docs) and keeping them in sync that is tedious. And that part can be automated. If there is a framework to build the whole bundle of docs from integration tests, integration test metadata, integration test artefacts, schemas, code and an assortment of high level explanatory texts then it stops being a chore. It actually becomes fun. It means that DDD becomes integration TDD. The only difference is that I will write an additional 3-4 explanatory sentences alongside the integration test I write before the feature and run a "docgen" script afterwards.
  - rapnie 3y ago
    What are your thoughts on BDD and Gherkin test scripts? The federated Diaspora* app has a BDD test suite [0], and for the Fediverse people are test-driving if it is applicable for ActivityPub compliance testing [1]. [0] https://github.com/diaspora/diaspora/tree/develop/features https://github.com/diaspora/diaspora/tree/develop/features [1] https://codeberg.org/helge/fediverse-features https://codeberg.org/helge/fediverse-features
    - hitchstory 3y ago
      I don't like gherkin. I think that it has awkward syntax, it lacks type safety, it's very verbose and doesn't have enough ability to abstract scenarios. Rather than being a source for generating the documentation it tries to be the documentation. Nonetheless, there is a small number of projects where they either work around these constraints or it doesn't matter as much, so it can work. I find that most people that apply gherkin to their projects run into a brick wall though - usually for one of the above reasons. I built https://github.com/hitchdev/hitchstory https://github.com/hitchdev/hitchstory as an alternative that has straightforward syntax (YAML), very strict type safety (StrictYAML), low verbosity and the ability to abstract scenarios. It is explicitly designed as a source for generating markdown documentation so that you can create richer docs like https://github.com/hitchdev/hitchstory/blob/master/examples/website/docs/correct-my-spelling.md https://github.com/hitchdev/hitchstory/blob/master/examples/... for your users rather than more test-like documents like https://github.com/diaspora/diaspora/blob/develop/features/mobile/change_password.feature https://github.com/diaspora/diaspora/blob/develop/features/m...
      - rapnie 3y ago
        Nice. I like the approach, thank you.
- nijave 3y ago
  Documentation is such a broad area I think it's big enough for everyone to hate something. There's - how (implementation, how the system works) - what (what the system is for, it's purpose - why (design) And there's audiences - developers (using the interfaces) - architects (designing the interfaces) - testers (validating the interfaces) - operators (running the system) - managers (organizing development efforts) And at some companies it's 1 person doing all of that. I think once you start to add more people, you start to have debates about documentation. The programmer might have written "clean" code and automated tests which are understandable to other programmers but less useful to project managers and operators.
vegetablepotpie 3y ago
This document is written from the perspective that a documentation writer is a dedicated role. In 10 years as an engineer I’ve never met a technical writer. It’s not a role I’ve ever seen hired. To address the question in a general sense, you need to address the case when the developers are the technical writers. How do you integrate documentation to your work flow? How do you justify the time spent to management? How do you make sure it’s useful to a customer?
- nijave 3y ago
  The companies I worked at with external facing documentation for their product (specifically APIs) had technical writers. One created a product with open source/closed source mix and had a dedicated person. The other worked with a contracting service to pay for a few weeks here and there when they were releasing something new.
- andylynch 3y ago
  I think it’s an under appreciated skill. I have worked on exactly one project with a technical writer (on retainer); the documentation was for a small internal audience but related to critical national infrastructure. It was money very well spent.
- euroderf 3y ago
  > How do you justify the time spent to management? A better (& simpler) way to approach it might be to get buy-in/consensus that after completion of an item, the developers as a group devote another 3%(?) of the accumulated development time to whatever documentation is required.
doggerel 3y ago
I think there are new solutions—and associated challenges—coming in this space as well. For example, there's a rise now in AI assistance for writing documentation. I think a large percentage of the documentation that produces is likely to be horrible to read and unusable. There's also things that work the other way. Rather than bloated AI docs you end up with frequently curated docs. For example, Runme is an OSS tool to make documentation interactive and runnable. In that scenario, your docs writer probably becomes an editor and UX eye on the documentation; the teams using the docs become the writers and updaters because they're executing out of them.
candiddevmike 3y ago
Keep your product documentation in the same repo as the product code and the convenience of being able to update it at the same time will manifest into more up to date documentation. Have the tech writers part of code reviews and rewrite things if necessary. Don't compartmentalize your product and the documentation for it. Developers don't hate documentation, they hate opening 15 PRs to get shit done.
- tbragin 3y ago
  Amen, especially for reference documentation, such as API or functions / SQL commands (e.g. for a database product). Those docs should be checked in with the code, and PR should not get merged if the docs are not ready.
- euroderf 3y ago
  "Docs As Code" is a concept in this space. It mostly assumes the use of Markdown & friends. Then it's probably left to the tech writer(s) to (a) automate the aggregation & assembly processes, and (b) make sure that their edits make it back to the code repos. AFAIK there's not a nice open source solution (or even toolset) for this.
  - candiddevmike 3y ago
    I use Docsy with great results: https://docsy.dev https://docsy.dev, e.g. https://github.com/candiddev/homechart/tree/main/hugo/content/docs https://github.com/candiddev/homechart/tree/main/hugo/conten...
    - euroderf 3y ago
      Does it (can it) work as something like a CCMS ?
simpaticoder 3y ago
The problem with documentation is that it's an untracked dependency with a slow, manual test procedure. An almost universal example of this is developer onboarding materials that are always (always!) out-of-date. In fact, most teams expect new devs to update the docs as part of their first tasks! (I think this is, in part, to measure a) their ability to deal with bad advice, and b) their willingness to make things easier for those that come after.) It would be great to invalidate documentation when the underlying code changes. There would be two levels of invalidation differentiated by probability: "these docs are definitely wrong now" and "these docs may be wrong and need to be checked." This is easier with APIs than with UIs but I've not seen it done with either. Some motion in this direction are, for example, IntelliJ's comprehensive refactoring support that can and will search documentation. I'm not really sure what a good solution looks like, but there's definitely a chunky problem to be solved here.
- euroderf 3y ago
  When features changed, I marked the associated documentation as "Preliminary", visibly indicating incompleteness. This marker was not sufficiently embarrassing to get developer time for documentation.
- euroderf 3y ago
  > a slow, manual test procedure End-users (i.e. documentation readers) are inevitably the last line of proofreading and docu-debugging. A nice idea I've seen is to put a "comment on this page" button tucked away in the corner of EVERY page.
tbragin 3y ago
They forgot the most common model - "add missing docs after the fact" :)

110 points by taubek 3y ago

The observation that hardcore True Developers™ absolutely hate documentation chores is maybe reflected in low upvote and comment count on this thread. But seriously, this is a good listing of pros and cons, and it is a pity not more experiences are shared. Commercial products usually pay good attention to the docs, but esp. FOSS projects are often severely under-documented. Model may be different here as often the single dev is the documenter too (and hates that chore). I tried Readme Driven Development [0] for a while, but found it still resource-intensive to keep things up-to-date. For single devs, small teams the Diátaxis framework [1] is helpful to organize and makes the task a bit lighter. [0] https://tom.preston-werner.com/2010/08/23/readme-driven-development.html https://tom.preston-werner.com/2010/08/23/readme-driven-deve... [1] https://diataxis.fr/ https://diataxis.fr/

verve_rat 3y ago
Everyone wants good documentation, no one wants to pay for a technical writer.
- euroderf 3y ago
  "I mean c'mon, how difficult can it be to write technically ?"
hitchstory 3y ago
I started doing documentation driven development a while back (with FOSS code) I wrote and I realized at some point that my tests and my how to docs were doing the same thing - one was just an easier to read version of the other. Moreover, when one went out of date so did the other. So, I tied them together - I wrote integration tests such that with a jinja2 template I could autogenerate readable markdown how-to docs from the tests and their artefacts. Setting that up led me to the realization that writing docs isn't actually tedious at all. It's the writing things down 3 times (spec, test & docs) and keeping them in sync that is tedious. And that part can be automated. If there is a framework to build the whole bundle of docs from integration tests, integration test metadata, integration test artefacts, schemas, code and an assortment of high level explanatory texts then it stops being a chore. It actually becomes fun. It means that DDD becomes integration TDD. The only difference is that I will write an additional 3-4 explanatory sentences alongside the integration test I write before the feature and run a "docgen" script afterwards.
- rapnie 3y ago
  What are your thoughts on BDD and Gherkin test scripts? The federated Diaspora* app has a BDD test suite [0], and for the Fediverse people are test-driving if it is applicable for ActivityPub compliance testing [1]. [0] https://github.com/diaspora/diaspora/tree/develop/features https://github.com/diaspora/diaspora/tree/develop/features [1] https://codeberg.org/helge/fediverse-features https://codeberg.org/helge/fediverse-features
  - hitchstory 3y ago
    I don't like gherkin. I think that it has awkward syntax, it lacks type safety, it's very verbose and doesn't have enough ability to abstract scenarios. Rather than being a source for generating the documentation it tries to be the documentation. Nonetheless, there is a small number of projects where they either work around these constraints or it doesn't matter as much, so it can work. I find that most people that apply gherkin to their projects run into a brick wall though - usually for one of the above reasons. I built https://github.com/hitchdev/hitchstory https://github.com/hitchdev/hitchstory as an alternative that has straightforward syntax (YAML), very strict type safety (StrictYAML), low verbosity and the ability to abstract scenarios. It is explicitly designed as a source for generating markdown documentation so that you can create richer docs like https://github.com/hitchdev/hitchstory/blob/master/examples/website/docs/correct-my-spelling.md https://github.com/hitchdev/hitchstory/blob/master/examples/... for your users rather than more test-like documents like https://github.com/diaspora/diaspora/blob/develop/features/mobile/change_password.feature https://github.com/diaspora/diaspora/blob/develop/features/m...
    - rapnie 3y ago
      Nice. I like the approach, thank you.
nijave 3y ago
Documentation is such a broad area I think it's big enough for everyone to hate something. There's - how (implementation, how the system works) - what (what the system is for, it's purpose - why (design) And there's audiences - developers (using the interfaces) - architects (designing the interfaces) - testers (validating the interfaces) - operators (running the system) - managers (organizing development efforts) And at some companies it's 1 person doing all of that. I think once you start to add more people, you start to have debates about documentation. The programmer might have written "clean" code and automated tests which are understandable to other programmers but less useful to project managers and operators.

vegetablepotpie 3y ago

This document is written from the perspective that a documentation writer is a dedicated role. In 10 years as an engineer I’ve never met a technical writer. It’s not a role I’ve ever seen hired. To address the question in a general sense, you need to address the case when the developers are the technical writers. How do you integrate documentation to your work flow? How do you justify the time spent to management? How do you make sure it’s useful to a customer?

nijave 3y ago
The companies I worked at with external facing documentation for their product (specifically APIs) had technical writers. One created a product with open source/closed source mix and had a dedicated person. The other worked with a contracting service to pay for a few weeks here and there when they were releasing something new.
andylynch 3y ago
I think it’s an under appreciated skill. I have worked on exactly one project with a technical writer (on retainer); the documentation was for a small internal audience but related to critical national infrastructure. It was money very well spent.
euroderf 3y ago
> How do you justify the time spent to management? A better (& simpler) way to approach it might be to get buy-in/consensus that after completion of an item, the developers as a group devote another 3%(?) of the accumulated development time to whatever documentation is required.

doggerel 3y ago

I think there are new solutions—and associated challenges—coming in this space as well. For example, there's a rise now in AI assistance for writing documentation. I think a large percentage of the documentation that produces is likely to be horrible to read and unusable. There's also things that work the other way. Rather than bloated AI docs you end up with frequently curated docs. For example, Runme is an OSS tool to make documentation interactive and runnable. In that scenario, your docs writer probably becomes an editor and UX eye on the documentation; the teams using the docs become the writers and updaters because they're executing out of them.

candiddevmike 3y ago

Keep your product documentation in the same repo as the product code and the convenience of being able to update it at the same time will manifest into more up to date documentation. Have the tech writers part of code reviews and rewrite things if necessary. Don't compartmentalize your product and the documentation for it. Developers don't hate documentation, they hate opening 15 PRs to get shit done.

tbragin 3y ago
Amen, especially for reference documentation, such as API or functions / SQL commands (e.g. for a database product). Those docs should be checked in with the code, and PR should not get merged if the docs are not ready.
euroderf 3y ago
"Docs As Code" is a concept in this space. It mostly assumes the use of Markdown & friends. Then it's probably left to the tech writer(s) to (a) automate the aggregation & assembly processes, and (b) make sure that their edits make it back to the code repos. AFAIK there's not a nice open source solution (or even toolset) for this.
- candiddevmike 3y ago
  I use Docsy with great results: https://docsy.dev https://docsy.dev, e.g. https://github.com/candiddev/homechart/tree/main/hugo/content/docs https://github.com/candiddev/homechart/tree/main/hugo/conten...
  - euroderf 3y ago
    Does it (can it) work as something like a CCMS ?

simpaticoder 3y ago

The problem with documentation is that it's an untracked dependency with a slow, manual test procedure. An almost universal example of this is developer onboarding materials that are always (always!) out-of-date. In fact, most teams expect new devs to update the docs as part of their first tasks! (I think this is, in part, to measure a) their ability to deal with bad advice, and b) their willingness to make things easier for those that come after.) It would be great to invalidate documentation when the underlying code changes. There would be two levels of invalidation differentiated by probability: "these docs are definitely wrong now" and "these docs may be wrong and need to be checked." This is easier with APIs than with UIs but I've not seen it done with either. Some motion in this direction are, for example, IntelliJ's comprehensive refactoring support that can and will search documentation. I'm not really sure what a good solution looks like, but there's definitely a chunky problem to be solved here.

euroderf 3y ago
When features changed, I marked the associated documentation as "Preliminary", visibly indicating incompleteness. This marker was not sufficiently embarrassing to get developer time for documentation.
euroderf 3y ago
> a slow, manual test procedure End-users (i.e. documentation readers) are inevitably the last line of proofreading and docu-debugging. A nice idea I've seen is to put a "comment on this page" button tucked away in the corner of EVERY page.

tbragin 3y ago

They forgot the most common model - "add missing docs after the fact" :)