Documentation Beta

TylerH

16:05

Is there a way to include some prose before example sets in a topic? Or are examples always the very first thing?

JonasCz

16:15

@TylerH Nope, examples are always at the top, you could use the remarks section, although it's not at the top, or make one example "pinned", so that it's always at the top.

TylerH

Seems kind of harmfully rigid

IMO it's best to be able to introduce a topic with some prose before you give examples

Otherwise you don't know what you're looking at

JonasCz

I agree. There's already a feature request requesting this, I think.

TylerH

Oh, excellent

Anil

for so docs beta, I think there's going to be alot of duplicate and crap content to filter through in the future, for e.g: docs-beta.stackexchange.com/documentation/php/194/variables/729/…

TylerH

@JonasCz Can you see the pending edit here? docs-beta.stackexchange.com/documentation/css/293/… per your feature request to see pending edits

JonasCz

16:21

No, I can't see it on that page. I approved it though.

TylerH

How'd you approve it if you couldn't see it?

JonasCz

I went to the tag dashboard, and there I can see it, just not on the topic page itself.

TylerH

Ah

in that case, upvoted

Trevor Clarke

17:13

hey guys

quick question: how do you make a new tag? I can't seem to get it to work

MSeifert

17:27

@TrevorClarke: docs-beta.stackexchange.com/questions/893/…

Trevor Clarke

so there needs to be a post on the tag?

MSeifert

I think all relevant tags are already possible (?) Also you need 3 people committing before it's open

Trevor Clarke

yeah

but like bootstrap

HireThisMarine

I've just been assigned to write documentation that will be comprised of dozens of html files that link to each other, have to work on older browsers, but the PC's that these docs will be viewed on will never be directly connected to the internet; anyone know if this kind of thing has a name?

MSeifert

project dump?

Trevor Clarke

17:33

Local Website

HireThisMarine

@TrevorClarke ooh thats a good start, thank you.

Trevor Clarke

@HireThisMarine np

TylerH

@TrevorClarke hopefully we don't need bootstrap documentation

because it's just CSS

TylerH

17:56

@JonasCz Found it docs-beta.stackexchange.com/questions/26/…

Neal

18:54

Hey @here. Why can't I comment on this "improvement" request? docs-beta.stackexchange.com/documentation/improvement-requests/…

I do not get what needs "improvement"

@NullReference are you in here?

TylerH

"This example is not helpful and should be edited or deleted"

Seems that NR, in the context of the rest of the example, didn't find it useful

Neal

literally all it is a is a hello world (ish) for js classes.

TylerH

You'd have to ask him to find out for sure

Neal

Yea, thats the issue. there is no way to comment lol

@KevinMontrose ^^

TylerH

My guess is that it doesn't explain what you are exemplifying

"Now you can do X" what is X and when would I do it?

Neal

18:58

That is not for the example. it is "Your first class"

Like any "Hello World" example

TylerH

Maybe edit it to say "Once you have declared the class, you can declare a new variable with that class as the type." or something

rather than just saying "now you can do"

because "do" isn't descriptive enough

Neal

Then why not edit? this voteing system for documentation is silly (in my opinion)

its not an answer or question that "needs" reputation...

TylerH

Maybe Null didn't have the time to think up a good edit but had enough time to read your description and think "that's probably not descriptive enough"

Neal

dunno

Anonymous

21:12

If we have disagreements about the best way to structure examples (whether things should be in one section or multiple, for example), could we submit multiple semi-redundant examples for the same topic and let voters decide which succeeds, or is redundancy like that to be avoided?

Adam Lear

you can try

I'm not sure the intent will come across clearly, though

probably best to take a stab at what you think is the best way to present an example and let others edit later if needed

Fractal

ugh... dat avatar

Neal

0

Q: Can we not let people with only 1 rep approve edits?

This edit (which I had already rejected once due to facts being wrong) http://docs-beta.stackexchange.com/documentation/proposed/changes/2959 was approved by a user with only one rep. Can we please set a higher threshold then 1 for edit approvals?

On that point @JeremyBanks there is no reason to create duplicate examples that have the same data in them.

Also @AdamLear is there any way we can improve on who can accept or reject edits. this seems a bit random.

This system is silly...

Adam Lear

@Neal Random?

Neal

@AdamLear Yes. anyone seems to be able to approve edits. Even users with no rep/1 rep

That does not make much sense where on the other sites you need to prove your self a bit first

especially for tag edits

Adam Lear

21:22

you need to remember that we're in a beta :)

there is no way to earn site rep here short of feature requests or bug reports

Neal

@AdamLear Yes, but everything from here will be moved over. I already Rejected an edit, but somehow another user with 1 rep approved it at the same time... How is that possible? (unless the same edit was put in 2x)

@AdamLear yes, examples get points as well

creating duplicate examples make no sense.

Getter was created as an example. Setters was created as an example. Getters and Setters is not needed as an example here docs-beta.stackexchange.com/documentation/javascript/197/…

So i rejected the edit

I just tried to revert the approved edit

but ther person who created it rejected it back @AdamLear

Anonymous

I feel like they should be a single post because they're so tightly tied together as a concept, and there's not enough complexity to require things to be broken down further.

Adam Lear

0

A: Can we not let people with only 1 rep approve edits?

After the beta is over, handling proposed changes will be tied to the "edit community wiki" privilege level (so, 100 reputation). I can see us extending this at some point to requiring X rep in the tag that's being documented, but that may turn out to be a) insane technically; b) negatively impa...

eh, gonna have edit wars no matter what

JonasCz

@JeremyBanks, Just curious, why did you change your name here and hide your linked accounts ? Just wondering..

Adam Lear

Since this is a beta and that includes coming up with rough "best practices" for documenting stuff, at this point I'd suggest opening a Q&A discussion @Neal

Anonymous

21:27

@JonasCz I hide all linked accounts because that lets me compulsively sign up for every new site without cluttering my profiles. And I used "Null Reference" here as a feeble petition for naming the site "Null Reference", which I advocated for on MSO. (Although not it's more of a joke than a real suggestion.)

Adam Lear

I wouldn't use potentially incomplete tools (approvals/rejections) to have the proverbial last word. talk to people and see if they have a compelling argument for doing what they're doing (I'm sure they're not just blindly clicking buttons... or at least I hope they aren't at this stage)

Neal

@AdamLear Yes, but the way it was implemented makes little sense. the approval process seems to be one and done. Should be some sort of overhead, not just one reject or one approval

MSeifert

If one person makes 4 proposed changes and 2 are incorrect and 1 incomplete and one really badly formatted is there any way to "report" him?

Adam Lear

gonna take 2 votes on prod as well

a lot of restrictions are relaxed because beta

although we can probably ratchet them back up now that there are more people involved (cc @KevinMontrose)

JonasCz

@MSeifert I'd think bring it up in the edit comments, chat, or on the site, first

Neal

21:31

Also the whole no comments on examples is harrowing. There should be some way to have a back and forth @AdamLear @KevinMontrose

@JeremyBanks stop putting comments as a reject reason

MSeifert

@Neal discussion-pages :)

Neal

@AdamLear please docs-beta.stackexchange.com/documentation/proposed/changes/…

Anonymous

talk:JavaScript

Neal

@JeremyBanks I have mutators in the example and I even say that it should not do that

there is no reason to have duplicate examples. if you want to put for for getters or setters put them in their respective examples that already exist.

I am going to keep submitting the same thing @JeremyBanks @AdamLear until this is fixed. use the comments. Stop rejecting

Use the comments

Adam Lear

@Neal er, good luck with that. on a related note, I just thought of a good way to get one's access suspended.

Anonymous

21:35

@Neal My example's setter/getter is more realistic. Recording set values while transparently getting the latest value as though it's the only one is behaviour you might get out of a mocking library. Suggesting that it's advocating poor practices is therefore silly, given that the existing example is mutating the class in a getter in a way that no real code should ever do.

Neal

@JeremyBanks I say that you should not do that. Separate the examples into their separate places. I can do that if you want

but comment on the post

dont just reject

Adam Lear

TALK to people and explain your reasoning. If they agree, great. If they don't, you have two options: try to convince them again or live with it. If you choose to be a nuisance and just spam the same edit... we have ways to "fix" that.

Neal

comments are for dicussion not the rejection reason

@AdamLear @JeremyBanks seems to be using the reject as a "comment" system

That is not what it is for

Anonymous

Neal, that seems to support my structure for the documentation. Your examples are awkward and contrived because you're splitting up getter and settter.

Anonymous

Mine is more realistic because they're being used together, which I also think is a clearer way to explain them.

Neal

21:37

@JeremyBanks They are separate entities even in the MDN docs lol

developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/…

different pages completely

Anonymous

The MDN docs provide many great examples of what we do not want to do. We're trying to find a better way.

Neal

No reaon to shmush them together lol

MSeifert

always nice: if you comment and the next one doesn't even care to read it and approves

or the proposer just retracts and submits again (which deletes the comments)

Neal

@JeremyBanks also in your "setter" you are just appending to an array. that is also antipattern

Adam Lear

being able to enter a custom rejection reason is pretty much exactly what that field is for. if you want to discuss something or you disagree with the comment... that's what chat or meta is for (in this case, the role of meta is played by the docs-beta site)

MSeifert

21:40

so we should actually discuss one-topic-related stuff in Documentation Q&A?

Neal

@JeremyBanks docs-beta.stackexchange.com/documentation/proposed/changes/…

MSeifert

NEVER DO MUTAION IN A GETTER <-- typo or slang word?

Neal

Hmmm @AdamLear the new editor does not seem to allow you to do Markdown headings. was that intentional?

@MSeifert typeo

Adam Lear

@MSeifert you can. figuring out what the best approach to documenting something is is part of the beta. normally these discussions could go on meta, but we don't have a meta right now, so...

Anonymous

The editor's preview doesn't entirely match up with the real results at the moment.

Neal

21:42

Fixed docs-beta.stackexchange.com/documentation/proposed/changes/…

Adam Lear

@Neal Hmm, not sure, actually.

kkhugs

@neal docs-beta.stackexchange.com/documentation/proposed/changes/2970

MSeifert

@JeremyBanks yeah, sometimes with amazing results ...

Adam Lear

Amazing? I like amazing. LETS SHIP IT

3

Neal

docs-beta.stackexchange.com/documentation/proposed/changes/…

@JeremyBanks maybe that will work. trying to use markdown header ^

Adam Lear

21:42

ahem Seriously, though. We're using commonmark instead of our usual markdown parser from Q&A, so there's probably bugs

Anonymous

<3 to the CommonMark effort.

JonasCz

@Neal - I don't like all caps, maybe bold / italic is enough ?
Also the header markup isn't working right, it shows the #
http://docs-beta.stackexchange.com/documentation/proposed/changes/2975?draftId=3513

kkhugs

@neal - do we really want to add examples of what NOT to do in documentation? Seems liek that could open a pretty large floodgate

Neal

@kkhugs Well if someone sees that and there is a big flag DONT DO THIS then hopefully people wont

MSeifert

@kkhugs I think what not to do is pretty well covered by the SO Questions :D

Neal

21:46

maybe a common pitfalls example may be better?

i dunno

kkhugs

yeah there are a lot of things that you shouldn't do, but i don't think we need to document them

Neal

@JonasCz I asked that above, it maybe working just the rendering on the drafts page may be wrong cc @AdamLear

kkhugs

but common pitfalls might be a good idea

Neal

People sometimes gloss over those.

kkhugs

@MSeifert too true.

MSeifert

21:47

but what's the difference between a common pitfall and what-not-to-do

convention?

Neal

@kkhugs consider approving mine then making a references section for common pitfalls maybe?

MSeifert

maybe just some links to StackOverflow Questions?

kkhugs

For an example of what not to do, please refer to this StackOverflow question: "Why does my getter return a different number every time?"

5

MSeifert

@kkhugs it might sound crazy because the purpose of Documentation is to provide examples to answer questions. Not to reference to SO Q&A. But in general: yes!

Neal

@kkhugs Does that question even exist?

I wanna make it! :-)

kkhugs

21:50

@Neal lol

that's the already-edited title of course, the original would have been more like "class.var return diff number everi tim?!?!"

MSeifert

you forgot about the "help plz!" or "asap"

kkhugs

^

Neal

0

Q: Why does my getter return a different number every time?

I have the following class: class Counter { constructor(start) { this.start = start; } set start(number) { this._start = number; } get start() { return this._start++; } next() { return this.start + 1; } } I instantiate it as f...

javascript scope ecmascript-6

@kkhugs ^^^^

MSeifert

Amazing ... there is a topic on python dictionaries and he doesn't even mention what's the class name of dictionaries: docs-beta.stackexchange.com/documentation/proposed/changes/2953

Neal

There ya go

Is that a good example of a "common" pitfall @JeremyBanks @MSeifert @kkhugs ?

anyways. gotta head home

o/

Adam Lear

22:01

o/

MSeifert

bye o/

Neal

lol thanks for the downvote whoever that was ;-P

MSeifert

I was the upvote on the question

Fractal

tempted to flag for vote-ringing ;-)

MSeifert

is that a word: vote-ringing?

Fractal

22:16

not really.

it has a meaning-ish ring to it though. </bad-puns>

Adam Lear

~/o On the twelfth day of christmas my true love sent to me... twelve votes a-ringing... o/~

kkhugs

22:37

@MSeifert @Neal @AdamLear there it's formalized now

0

Q: Should we document examples of what NOT to do?

Is Documentation a place where we want to collect examples that explain how to make the people who inherit your code want claw their eyes out? Or should we leave that to the PHP site's comment section? A suggestion was brought up in chat that while bad examples might be a thing to avoid, common ...

discussion

MSeifert

I was the one who said it was covered by SO questions :D

would it be a good idea to have a "guidelines for documenting this tag" topic?

Adam Lear

I'd expect that to depend on the tag

or, rather, most tags should be documentable in roughly the same way

MSeifert

ok, I'll just submit it and see what the others think

Adam Lear

the rest can probably go into the remarks in hello world?

there's no way to "pin" topics, so a topic sounds like a bad fit for that sort of guidance

MSeifert

that's a good idea ... putting it in the "Hello World".

Adam Lear

22:49

I can see the need for something like "this is how we like to do things around here". Would love to see some real-life examples first before building out a feature for it, though.

Fractal

@MSeifert no, I don't think so. Well, at least for the php tag, I'm pretty sure any guideline would be contradicted by many people. let's leave the system take care of how and who contributes

MSeifert

I was thinking about python. And I've proposed a topic: docs-beta.stackexchange.com/documentation/proposed/changes/2993

let's see if anyone wants it. :)

ah, should have avoided the "Don't do it like this"-sections ...

Transcript for