Making world-class docs takes effort

Re:Making world-class docs takes effort by sokoloff on Monday September 06, 2021 @03:46PM (#28437241)

Twice in my career I’ve implemented a system to generate “good docs” from source. Twice I’ve failed. I’ve seen several other such initiatives which also failed. In every case, a more friendly editing experience won over the “check it in and type ‘make doc’” experience. That could have been MediaWiki, Confluence, Box notes. People even preferred the abomination that is Sharepoint over a source-based system.

If your docs are only written by developers, you might have a chance to make it work. If you need docs to be also written/edited by non-devs, I think you’re looking at an uphill path to get everyone into source control-based docs.

[ Parent | on HN ]

Re:Making world-class docs takes effort by simonw on Monday September 06, 2021 @04:10PM (#28437519)

That's absolutely true: the golden rule of keeping docs with code assumes that the documentation is /about/ the code - class and function descriptions or web API documentation for example.

For product-level user-facing documentation written by non-engineers I think it's entirely appropriate to use a different tool.

[ Parent | on HN ]

Re:Making world-class docs takes effort by yourapostasy on Monday September 06, 2021 @10:41PM (#28440295)

> For product-level user-facing documentation written by non-engineers I think it's entirely appropriate to use a different tool.

I fantasize about an environment where a GUI's internals and interfaces are annotated sufficiently to discretely call from unit and integration tests, and version-controlled instances of those are linked to non-technical task management, user documentation, support tickets, support knowledge bases, patch configuration management, and so on. In this fantasy, if code changes a GUI element enough to alter its appearance or fail a unit test of the GUI, it automatically triggers a re-imaging of snapshots for it in all downstream linked documentation references and issues PR's for human intervention reviews of the new images (with adjustable cropping for finalized approvals).

That's my holy grail of single-source documentation.

[ Parent | on HN ]

Re:Making world-class docs takes effort by fragmede on Monday September 06, 2021 @06:49PM (#28438984)

"product-level user-facing documentation written by non-engineers" is at one end of the spectrum, and clearly wants to use a different tool (eg Adobe InDesign) with code comments written by engineers at the other. Problem is, how do you navigate everything else that's in-between, while minimizing strife from one side making demands (some reasonable, others not) to the other.

Where do your business critical spreadsheets go?

[ Parent | on HN ]

Re:Making world-class docs takes effort by simonw on Monday September 06, 2021 @07:19PM (#28439177)

I think most documentation at a company can and should live outside of version control repositories - the key thing is to have editing tools that non-engineers can use and to ensure that the resulting material can be effectively published, searched and made visible to the people who need access to it.

The exception is engineering documentation: API docs should absolutely be version-controlled in the same place as the code they are describing.

I built an internal search engine for a past employer that covered 11 different sources of documentation - Confluence, Google Docs, GitHub Markdown, Salesforce Support and more - and it really helped solve some of the discoverability problems we were having.

[ Parent | on HN ]