If anyone tells you that writing documentation is easy, please shoot them. I started working on this over a month ago and only just released it today (19th May 2019) due to the length of time the documentation took. So why go to the trouble? That’s down to my philosophy of “Without proper docs how the beep are people supposed to know how to use what you make?”.
Anyway, in case you missed the link on the vault’s front page (or it’s months later and it’s dropped off the front page) here is the link to what I am talking about.
Any requests for additional content may have to wait a couple of weeks as I seek a dark, quiet room to melt back into reality while gibbering in the corner.
Oh and comments (on topic only) are good too.
I ear you. Writing documentation is the ungrateful part, but it is necessary for software creations to be enjoyed (and as paradoxal as it seems, rare are the intrepid souls that read them). To make it easier, i try to document in parallel as i progress in the programming/making process. I don’t know what tools others use, but i am a KISS (Keep It Simple Stupid) adept, so for me it is all ASCII text and txt editors.
By the way, congrats on your new Nwn package ! I am surprised you can assume a pyramide or diamond shape but, mmm, maybe polymorph…
A cube. I’m 100% square maaaaan.
I use word (I saved up and got the home & student version of office) mostly to create the documents. Then if I’ve got bold text in one or more tables (I love using tables) I use LibreOffice Writer to convert to pdf. In all other cases I use Word for the conversion. I mainly use pdf because it is portable and it supports bookmarks which I include in all my docs. Makes it easier for people to find what they are looking for. Then some of them insist on using a browser plug-in (which doesn’t support bookmarks) to read pdf docs…
Then there are the tl:dr crowd…
Actually comments on the documentation would help me to produce better docs but…
Word can export to PDF too, but Writer can do pretty much the same for whole $0. The biggest problem with it is that you eventually run into people who use Word exclusively with weirdo fonts, over-complicated tables that LO will render really badly.
My approach is to make software self-document. With libraries I skip internal comments, but instead focus on docstrings, which: 1) can be easily seen in the toolset, 2) can be extracted from the code itself and easily turned into an API reference. See example.