Why Your Company's Documentation Sucks

• Optic

  12 1,280 9.8 TypeScript

  OpenAPI linting, diffing and testing. Optic helps prevent breaking changes, publish accurate documentation and improve the design of your APIs.

  

Our documentation sucks because it is time-consuming to do documentation properly.

I am hoping to fix this by introducing Optic [0] to automatically handle generating API diffs.

[0]: https://github.com/opticdev/optic

• mm-docs-template

  1 7 7.3 PowerShell

  Template to use with mm-docs

This view is too much simplified. If docs where tree vs graph we would probably have at least some orgs doing it right, while there are literarily almost zero.

Some of the important aspects of good documentation is:

1. Narrative style. You can't do ad hoc whatever wherever and call it a day. Most people don't have it and many are quite illiterate IMO. You need to practice this and most engineers don't like that. Hell, even most seniors don't like writing tickets IME which take almost the same time as putting garbage on Slack. I created templates on both GH and GL and almost nobody uses them even tho you don't need to think about anything but follow few rules.

2. Its quite hard to know what level of detail to put in documentation. You need a lot of experience for this - put to much, and it gets quickly outdated, put too little, and it doesn't convey much. Good documentation exists on multiple levels - as bunch of markup files "on the spot", as formal hi and low level documentation and also those are usually affecting different target groups so you actually need to design docs.

3. Documentation is a service. It has source code, build procedure, automatic link checking, export to bunch of format, crosslinks, variables, macros, configuration for different environments, abbreviations, definitions. Its quite hard to get it right. After years of struggle on different projects I finally created my own stuff [1] that I use on all projects, for docs spanning 50-500 pages. I maintain that for years now, constantly (so yeah, its a job).

[1]: https://github.com/majkinetor/mm-docs-template

• SurveyJS

  surveyjs.io sponsored

  Open-Source JSON Form Builder to Create Dynamic Forms Right in Your App. With SurveyJS form UI libraries, you can build and style forms in a fully-integrated drag & drop form builder, render them in your JS app, and store form submission data in any backend, inc. PHP, ASP.NET Core, and Node.js.

  

Suggest a related project