Hacker News new | ask | show | jobs
by sametmax 2975 days ago
How do you fit deployment doc in code ? And tutorials ? General graphs of the architecture ?

Because an API reference is a very poor doc.

2 comments

Ideally your deployments are code. And tutorials are part of your website 'code', or integrated into your project (and thus 'code'). General graphs of the architecture would be docs in your code repo (and thus 'code' too). I'll admit tho that it's pretty sensible to just not consider some of those as 'code' and thus conclude that documentation outside of the code is important too.

But the original commenter is also probably right that 'second hand' documentation is probably the least accurate.

These documents are still things that can become out of date. Anything of this nature can be in a source file somewhere, even if it’s a giant overview comment in one of the main files.

I do think it’s fine to create pretty docs from source comments or generate pictures from graph descriptions, etc. Every generated page should clearly state where it came from though (e.g. revision number and date).

Frankly I don’t like having only an API doc without the implementation. Code should be open-source to those using it, under NDA if necessary. When I need to rely on hidden implementations from Apple, etc. I routinely have to waste time discovering things simply not working as described. Meaning, their pretty docs are out of sync with reality and it wastes significant time to find this out the hard way.