News for hackers. Stuff that matters.

A comment on The case for continuous documentation. Parent comment

Re:The case for continuous documentation by zelphirkalt on Tuesday June 08, 2021 @05:01AM (#27432078)
That is an interesting approach as well. What I see as advantages are: that there is no need for a specification and no need for it to be rendered, as one is to view it as plain text.

What I see as disadvantages are: It is not possible to render it properly or have support for it beyond showing plain text. Many users might write things different from each other, which might affect how easily a reader picks up what each document's style or conventions are.

[ Parent | on HN ]
Re:The case for continuous documentation by a1369209993 on Tuesday June 08, 2021 @03:14PM (#27439538)
> It is not possible to render it properly or have support for it beyond showing plain text.

Sure you can, and indeed that's what markdown was originally supposed to do (at least as it was first described to me). The catch is that you have to treat the plain text as the authoritative version: you do not edit the plain text in order to produce changes in the rendered document; you edit the plain text for it's own sake, without considering the effect on the rendered version, and the rendered version is derived from that.

[ Parent | on HN ]