Writing Documentation Sucks


  • SockDev

    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.

    <!-- Posted by SockBot 0.15.1 "Zany Zoe" on Sun, 11 Jan 2015 18:12:58 GMT-->

  • SockDev

    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 :eek: YAML :eek:



  • @accalia said:

    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. :angry:


  • SockDev

    well i plan to be different! there will be good documetation! OR ELSE!

    :anger: :angry: :tangerine:


  • SockDev

    yes. examples required!


  • SockDev

    @RaceProUK said:

    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.


  • SockDev

    hmm..... now this has promise....

    https://staradept.com/sockbot/modules/autolikes/

    i can work with this i think.


  • Discourse touched me in a no-no place

    @accalia said:

    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.


  • BINNED

    @FrostCat said:

    man pages...
    the good ones

    There's such a thing?
    :flamebait:


  • mod

    @accalia said:

    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.


  • SockDev

    @abarker said:

    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/

    @abarker said:

    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.


  • mod

    @accalia said:

    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.


  • SockDev

    @abarker said:

    KSP

    i like where your priorities are.

    i like it less that you aren't posting screen shots!

    :-D



  • @abarker said:

    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.


  • Discourse touched me in a no-no place

    @Jaloopa said:

    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.


  • SockDev

    i have read many man pages..... i would call none of them "good"



  • Same here, I normally stop after the fun part


Log in to reply
 

Looks like your connection to What the Daily WTF? was lost, please wait while we try to reconnect.