Proofreading Technical Writer Wanted.


  • sockdevs

    SockDrawer*, Is looking for someone who is willing to spend a couple of hours giving our documentation a once over, to help spot the @accalia and gramming errors, as well as point out to us spots in our documentation that are missing or lack as full an explanation as they deserve.

    Our documentation is currently hosted on readthedocs with the source markdown available on github

    If anyone is interested in performing such a service please drop me a line, either here or via PM. Comments, questions, constructive criticism, and offers to help are all appreciated!

    * a division of Lexicon Industries**
    ** a division of Syncorp Technologies***
    *** a division of Acorn & Associates Holdings****
    **** a division of Lexicon Industries


  • Winner of the 2016 Presidential Election

    @accalia said:

    * a division of Lexicon Industries**
    ** a division of Syncorp Technologies***
    *** a division of Acorn & Associates Holdings****
    **** a division of Lexicon Industries

    E_STACK_OVERFLOW


  • sockdevs

    Maybe it would be a good idea to implement tail call recursion to help prevent stack overflows like that?


  • Winner of the 2016 Presidential Election

    Perhaps. As it is, I get

    a division of Lexicon Industries
    a division of Syncorp Technologies
    a division of Acorn & Associates Holdings
    a division of Lexicon Industries
    a division of Syncorp Technologies
    a division of Acorn & Associates Holdings
    a division of Lexicon Industries
    a division of Syncorp Technologies
    a division of Acorn & Associates Holdings
    a division of Lexicon Industries
    a division of Syncorp Technologies
    a division of Acorn & Associates Holdings
    a division of Lexicon Industries
    a division of Syncorp Technologies
    a division of Acorn & Associates Holdings
    a division of Lexicon Industries
    a division of Syncorp Technologies
    a division of Acorn & Associates Holdings
    a division of Lexicon Industries
    a division of Syncorp Technologies
    a division of Acorn & Associates Holdings
    a division of Lexicon Industries
    a division of Syncorp Technologies
    a division of Acorn & Associates Holdings
    a division of Lexicon Industries
    a division of Syncorp Technologies
    a division of Acorn & Associates Holdings
    a division of Lexicon Industries
    a division of Syncorp Technologies
    a division of Acorn & Associates Holdings
    a division of Lexicon Industries
    a division of Syncorp Technologies
    a division of Acorn & Associates Holdings
    a division of Lexicon Industries
    a division of Syncorp Technologies
    a division of Acorn & Associates Holdings
    a division of Lexicon Industries
    a division of Syncorp Technologies
    a division of Acorn & Associates Holdings
    a division of Lexicon Industries
    a division of Syncorp Technologies
    a division of Acorn & Associates Holdings
    a division of Lexicon Industries
    a division of Syncorp Technologies
    a division of Acorn & Associates Holdings
    a division of Lexicon Industries
    a division of Syncorp Technologies
    a division of Acorn & Associates Holdings
    a division of Lexicon Industries
    a division of Syncorp Technologies
    a division of Acorn & Associates Holdings
    a division of Lexicon Industries
    ...
    ...
    E_STACK_OVERFLOW
    


  • @accalia said:

    spot the @accalia and gramming errors,

    That rules me out then


  • sockdevs

    there are more things we're looking for from the review. :smiley:

    you can help with those!



  • That's actually what I studied in college. And I'm currently looking for freelance work.


  • sockdevs

    I'm afraid we have no budget for paid work, but if you're willing to donate some time to keep in practice we will happily accept it and make sure you get proper attribution in the documentation.



  • @accalia said:

    for your portfolio.

    *twitch*

    You know those words are a berserk button for anybody doing creative work, right?


  • sockdevs

    until now, no i didn't.

    uhh.... sorry?



  • Well as an ESL I don't trust proofreading my own articles, so I don't care much, but I thought that "'it'll look good in a portfolio' is an insult of the highest degree" was common knowledge...


  • sockdevs

    hmm.... point taken. BRB.

    /me runs off to her time machine that doesn't work too good to correct the matter



  • @accalia said:

    * a division of Lexicon Industries**
    ** a division of Syncorp Technologies***
    *** a division of Acorn & Associates Holdings****
    **** a division of Lexicon Industries

    You are in a maze of twisty little divisions, all alike.



  • There are So many requests for work, with the payment being 'shite-in-yer-pertferlier'. I'M TRIGGERED!


  • sockdevs

    yes, yes, my mistake, you made your point.

    -_-

    @accalia did a bad.



  • @accalia said:

    @accalia did a bad.

    Soo... not something for your portfolio then?


  • sockdevs

    -_-

    look, i made a bad, can we get back to the point of the thread?

    If you'd like to help that's awesome but harping on my mispost is not helping.


  • Discourse touched me in a no-no place

    @accalia said:

    but harping on my mispost is not helping.

    But it is kind of funny. Oh, less so to you, yess.



  • @accalia said:

    look, i made a bad, can we get back to the point of the thread?

    I heartily agree. We can take this portfolio business elsewhere to trolltriggermicroaggress the creative types on TDWTF.





  • Classic.


  • sockdevs

    yes, yes.

    I can't help feel that the message is rather different, or at least the intent is.

    in those stories y'all have been linking the tone is very much "DO WORK FOR ME FOR FREE BECAUSE I AM THE CUSTOMER!"

    where the tone SockDrawer is trying for is more "Hey, we've got a thing that needs some skills, you have skills. would you like to help? we can't pay you, but we'll give you proper credit if you're interested. If you're not interested that's cool. Thanks!"



  • I'll clone the repo and take a look this weekend if I have time. Maybe I'll submit a PR.


  • sockdevs

    we'd appreciate it! :-D



  • Do you have any particular priorities? If I donate time, I want to be as big a help as possible.


  • sockdevs

    I would say the non API docs are higher priority than the api docs. those are meant for non developers so should be easier to understand

    but really any help you can be would be appreciated!



  • Had a quick read through the "hosted" documentation. Some typos, some presentation inconsistencies, some confusion over a Method being a getter or setter. Not sure who the document is aimed at - informal wording but no real explanation or usage.

    Not a criticism, just a first pass impression (I was scoping out the job) I haven't decide If I need to see the source to validate the documentation.


  • sockdevs

    @loose said:

    Some typos

    i did try to avoid those....

    @loose said:

    some confusion over a Method being a getter or setter

    ... don't recall any of that in sockbot2.0... but if you remember where you saw that i'll make sure they get foxed.fixed

    @loose said:

    Not sure who the document is aimed at - informal wording but no real explanation or usage.
    see, now that's why i need a technical writer to point that sort of stuff out to me! :smiley:

    The intended audience is both users of sockbot (and i suspect that that side is rather lacking) and people developing for sockbot, ehiter by creating new plugins or by working on core.

    I don't think i did a good job organizing things to support that to be honest.

    @loose said:

    Not a criticism, just a first pass impression (I was scoping out the job)
    And appreciated it is.

    Thanks for your time!



  • I have only ever produced one set of technical documents and that was for a single Module of a Pearl Project that was, essentially, a single Factory to produce and implement @ 120 data objects / entities. Other Modules used the combination of the script / PearlDoc for each data object as they would only have a few of them.

    To do this, I had to parse all the configuration and database files and present in some form of readable API documentation. And because I am me, I made it fully automated an relatively bullet proof because they kept changing then name of things, adding and removing stuff etc.

    Somewhere there was a manually updated (C type) definition file which they needed for their code to compile, or something. So I knew that would always be up to date. So that was my starting point. With a name I could start sniffing around the DB creation Files to get data type and constraints etc.

    Essentially, and I know the pedants are going to love this, It would "re-document itself" (if required, and you were not looking at a cached version) every time it was run. - I'm hunting around to find some examples



  • @accalia said:

    "DO WORK FOR ME FOR FREE BECAUSE I AM THE CUSTOMER!"

    http://www.27bslash6.com/bob.html

    I love this one.

    @accalia said:

    . If you're not interested that's cool. Thanks!"

    And that's fine. I don't think anyone has any objections to this. The funny thing was the mention of a portfolio - which is (AFAIK) essentially worthless.
    It was funny - nobody hates you (besides the obvious).

    I just like the stories ☺



  • Comments thus far:
    The docs seem to be missing the license.

    There seem to be a few accalias.
    Is there any easy way to edit multiple documents and make one PR on github, or do i have do clone it and do it locally ?


  • sockdevs

    fork and PR is the easy way to do multi edit.

    if you don't do github or don't want to you can download and send me a zipfile of the edits and i'll commit for you.


  • sockdevs

    @swayde said:

    http://www.27bslash6.com/bob.html

    Once, I locked my office door and spent the day nude.

    :laughing:


  • Discourse touched me in a no-no place

    @accalia said:

    fork and PR is the easy way to do multi edit.

    There you go, the simpler parts of the documentation are now a bit more proof-read than before, with speeling and gramming slightly less characteristic of your good self. (I've done a lot of document editing, so that sort of thing is easy for me.) My main criticism at this point is that there's still a lack of high-level documentation, a map of the functionality, where would I go in the code to start using it and hacking it around, and how do the pieces fit together (since it is definitely developer-oriented documentation in the first place). I can't write that for you; I just know that it's still rather mystifying code as a whole. :smile:

    What's more, I'm not a technical writer and I don't give two hoots about “portfolio” BS. I do this because I want to, and that's that.


  • sockdevs

    @dkf said:

    There you go, the simpler parts of the documentation are now a bit more proof-read than before, with speeling and gramming slightly less characteristic of your good self.

    /me claps

    excellent! Thank you!

    @dkf said:

    My main criticism at this point is that there's still a lack of high-level documentation, a map of the functionality, where would I go in the code to start using it and hacking it around, and how do the pieces fit together
    that is a lack. Do you have any suggestions of how we should lay that out?

    We've (okay, I've) got the knowledge, but we;re not sure how to lay it out to be the most accessible.

    @dkf said:

    I can't write that for you; I just know that it's still rather mystifying code as a whole.
    trust me, this code is a million times less mystifying thatn the original version. ;-) (still pretty mystifying though)


  • Discourse touched me in a no-no place

    @accalia said:

    that is a lack. Do you have any suggestions of how we should lay that out?

    A picture? Pictures are good, telling the story of a thousand words, etc.

    Try a pseudo class/collaboration diagram. Yes, UML sucks, but you've not got many classes and just showing how the things hang together helps a lot. It also helps if you give some sort of impression of which things are singletons (real or by-configuration) and which will be instantiated a lot. I like to do that by showing the multiply-instantiated ones as a stack of boxes, all on top of each other, because people look at it and say immediately “ah, it's one of a lot of things”.

    Once you've got a picture, write the words to tell the “story” in the picture. :smile: There's no harm in trying to say the things twice (or more) in different ways: between them, you might even get it right. Or at least that's how I do it.

    The aim is to get it so that when some new developer comes in, they have a mental model for how the piece they're working on fits with the rest, not just the interface, but if you will the reverse interface. Ask not what you code can do for SockBot, ask what SockBot assumes of your code. To paraphrase…


  • sockdevs

    @dkf said:

    Yes, UML sucks, but you've not got many classes and just showing how the things hang together helps a lot.

    Depending on your definition of class, we have exactly one: PostBuffer :stuck_out_tongue:

    But we do have many modules, so I guess that's what you really mean.


  • Discourse touched me in a no-no place

    @RaceProUK said:

    But we do have many modules, so I guess that's what you really mean.

    Exactly. Here I am, happily misunderstanding the code, and then you go and start explaining stuff.


  • sockdevs

    @dkf said:

    Yes, UML sucks, but you've not got many classes and just showing how the things hang together helps a lot.

    hmm.... yes.

    now i have to remember how to write the damn things, that's more complicated than reading them (not by much, but enough)




Log in to reply
 

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