-16

I've recently made a tentative attempt at helping create some initial documentation for XSLT 2.0.

It's come back with lots of comments from "Community" which appears to be a robot.

Sorry, but I am not going to write English text to be read and assessed by robots. Forget it. I know what readers need better than any robot does - after all, I've written a popular book on the subject. I'm prepared to do lots of things to help the user community, but I'm not prepared to descend to this.

And sorry, I know this is a rant and not a real question, but it has to go somewhere.

12
  • 16
    And how should we know that we are not talking to a robot right now who asked this question?
    – Rizier123
    Commented Aug 11, 2016 at 7:37
  • We expect you to write documentation to satisfy the interested ones in that topic. If it's a "robot" or a noob what reads it whats the issue? If you do it for the community then it doesn't matter who reads it, does it?
    – Raskayu
    Commented Aug 11, 2016 at 7:43
  • 19
    Could you include or point us to those comments?
    – Bart
    Commented Aug 11, 2016 at 7:53
  • 1
    I'm writing docs for people in the FUTURE. don't really mind the robot, it's just there to help out.
    – svarog
    Commented Aug 11, 2016 at 8:15
  • 6
    "it has to go somewhere" - and why should that somewhere be here?
    – jonrsharpe
    Commented Aug 11, 2016 at 8:15
  • 4
    What comments even where there? Im curious
    – Magisch
    Commented Aug 11, 2016 at 8:29
  • 2
    Your post gives the impression that you think the Community user is some form of AI, unleashed upon us by SO and designed to tell us mortal beings how things should be done. It's not. It's just a background process that helps keep things clean.
    – user247702
    Commented Aug 11, 2016 at 9:02
  • 4
    Ugh, your robophobia is triggering me.
    – user1228
    Commented Aug 11, 2016 at 15:11
  • 4
    I don't understand why this question is on hold as unclear. Clearly he proposes to have only human reviewers. I personally tend to disagree, because this is a free site and it would be hard to recruit motivated volunteers to replace what a background process can do. But the question is clear for sure. Yes, the style is admittedly "explicit", but not to the point of being regarded as offensive. Banning criticism is never a good idea: it will not lead to sack the robot, but might spur building a better one.
    – antonio
    Commented Aug 11, 2016 at 15:45
  • 1
    @antonio I think most users voting to close this question didn't understand what comments OP is talking about (note the number of upvotes on Bart's comment). If they've only visited popular tags in Documentation, it's highly likely they've never seen those automatically generated improvement requests.
    – Athari
    Commented Aug 11, 2016 at 17:29
  • @antonio: I don't think the "question" is that clear at all. In fact Mr. Kay admits it's not a real question but a rant. Since he doesn't point us to the comments, and few of us have seen them, it's difficult to have any clear notion what he's objecting to. We can make assumptions about the type of comments he's referring to (as in Squidward's answer), but those are easy to dismiss, so it's hard to understand why the OP would be so annoyed by them. Is he really proposing that the auto-advice be removed, even for helping noobs learn how the docs system works?
    – LarsH
    Commented Aug 16, 2016 at 2:05
  • 3
    I think I basically disagree with the premise that good documentation starts with examples. I think it starts with clear explanations of concepts and terminology. So, since I'm working with a technical editor that is automated and won't listen to my opinions, I shall refrain from contributing in future. Commented Aug 17, 2016 at 7:50

1 Answer 1

37

I guess you refer to these comments from Community user:

Improvements requested by Community♦, Community♦, Community♦:

  • This topic would benefit from additional syntax notation, explanation of parameters, or remarks. ×2
    Comments:
    • Add a Version section, describing the major releases of zend-framework2 along with links to release notes. - Community
    • Replace the default remarks section with a descriptive overview of zend-framework2. - Community
  • This topic would benefit from examples that don't currently exist.
    Comments:
    • Add an example which shows how to build a "Hello World" program or an equivalent thing in zend-framework2. - Community

These comments are just an instruction on how to get started with writing Documentation for a tag. They're created for every single tag once a proposal is accepted. They're important because it's far from obvious that adding a list of versions is crucial, as they're used throughout the tag. "Hello world" example is important because the first introductory topic in the tag is undeletable and is displayed on the side bar. Not sure about the remarks section — probably a generic recommendation.

These comments just explain how the system works. They don't tell you what to write about and how to write. They explain important functionality.

Why the Community user was used to list these instructions? Probably because Documentation includes a system of improvement requests and these comments are improvement requests at the core. You can just dismiss them, like any other requests, but it's probably a good idea to listen to them.

Overall, I don't see how these comments are any different from instructions which you get on the side panel when you edit a post (not in inline mode). You don't complain that you wrote a book on Markdown and so don't need any instructions on using italic, do you?

3
  • 7
    Well, I've got a little bit used to the SO paternalism that objects, for example, when an answer is too short, even though I've said everything that needs to be said. I still hate it, but I put up with it. The difference is that answering questions is basically a reactive activity. Starting a new set of documentation is a creative activity that demands serious thought about the best order in which to present concepts, and having an idiot robot tell you that you've got it wrong has one effect only: it puts me off sufficiently that I'm not going to try it again. Commented Aug 12, 2016 at 16:36
  • 9
    @MichaelKay If you want to have freedom and full control, Documentation is probably not the best idea. It's more like "Random Examples on Random Topics in Random Order" than "Documentation".
    – Athari
    Commented Aug 12, 2016 at 16:43
  • 4
    +1. Community won’t be reviewing your changes. The comments/improvement requests are just to guide you in the right direction, and if you click ”Dismiss,” they’ll be gone forever.
    – Jed Fox
    Commented Aug 12, 2016 at 23:49

Not the answer you're looking for? Browse other questions tagged .