Writing Documentation Sucks
-
So i'm starting to write proper documentation for @sockbot and it sucks! I mean i know i want to document it so ti can be used and developed on by others, but i have no idea how to go about that.
Obviously i need to document the code, but that's not my priority right now. i want to get solid usage documents including the configuration file formats (there are two of them.... although i do plan on switching the main config file to YAML soon. i will do it by the 0.16.0 release of sockbot.
anyway.... are there any resources that y'all recommend i look at to help me write documentation that doesn't suck?
or would you be interested in trying your hand at writing some of it for me? no? oh. well then want to Kibitz on what i write?
-
@accalia has summoned me, and so I appear.
-
Documenting the config should be easy enough: just have a few tables with Parameter/Usage/Valid Values columns ;)
-
And examples, considering it's in JSON and/or YAML
-
usage documents including the configuration file formats
This is the worst. Everywhere. They tell you what the options are, but not how to set stuff up, or what valid values are.
-
well i plan to be different! there will be good documetation! OR ELSE!
-
yes. examples required!
-
just have a few tables with Parameter/Usage/Valid Values columns
hmm...... that...... that shows promise.
let me run with that for a bit and see what happens.
-
hmm..... now this has promise....
https://staradept.com/sockbot/modules/autolikes/
i can work with this i think.
-
yes. examples required!
Read some man pages. The bad ones give you hints of what not to do (e.g., they don't explain what the options do, just what they are) and the good ones give you hints of what to do, as in the narrative structure. The nice thing is that they generally have an outline you can follow: usage, explanation of options, how the options work and what they do, and so on.
-
-
So i'm starting to write proper documentation for @sockbot and it sucks!
Yes, documenting seems to be a necessary evil. This is part of why WTForum development is starting slow. I'm insisting on having the requirements for a module documented before that module is written. While it's a PITA, it should make it easier to write automated tests and to write user documentation. Of course, that's all theory, so we'll see.
-
Yes, documenting seems to be a necessary evil.
it's why i'm doing it now. enough people are using sockbot that i need to document it. i could get away when it was just me having fun... but not so much anymore.
but i have a good start i think. dicumenting the modules, including sample configurations. i'll want someone to go over it all soon and slap me upside the head with any issues so i can get them fixed....
https://staradept.com/sockbot/modules/
While it's a PITA, it should make it easier to write automated tests and to write user documentation.
at least you control the entire stack. i have no idea how i would harness sockbot to automated test the code....
i also need to pull your code soon and see what's up with it... :-D maybe i can break it in a creative way.
-
i also need to pull your code soon and see what's up with it... maybe i can break it in a creative way.
First I've got to put some up. I've just finished selecting a hosting instance and a DB option. Now that I know what I'm working against, I'm ready to write some code.
It's hard keeping things moving between work, family time, KSP, Assassin's Creed, etc.
-
KSP
i like where your priorities are.
i like it less that you aren't posting screen shots!
:-D
-
Yes, documenting seems to be a necessary evil. This is part of why WTForum development is starting slow. I'm insisting on having the requirements for a module documented before that module is written.
This is, in part, why some of my personal projects have faltered. I want to engineer them correctly, but lose interest before I've gotten through the drudgery.
-
There's such a thing?
Yes, actually. Don't ask me to name any specific ones; I haven't read a man page in years.
-
i have read many man pages..... i would call none of them "good"
-
Same here, I normally stop after the fun part