We're back from the holidays, and not withstanding a few mishaps, back to work full speed on Documentation.
Only a couple new things today.
Documentation events in you User Profile
You documentation activity is now exposed in your user profile, just like any other sort of activity.
Java and...
On first sight the documentation overview is a bit confusing. But that may be caused by the little content (Java). Looking at the .NET documentation makes things clear to me.
@user714965 yeah, the initial state is a little... sparse. There's a little chicken-egg problem to work out there, we've made some drastic changes to the dashboard page during the beta based on actual use. I think we're closing in on a good end state though.
@bjb568 you signed up for javascript iirc; we've only got java, android, .net, & c# up right now... if you want to change to one of those I can do it and you'll get an invite.
For something like this docs-beta.stackexchange.com/documentation/proposed/changes/672 I'm not sure that 600 characters is enough to have a proper discussion with suggestions. It's not an edit - this is a first go at this page. Should we be treating these like a PR on Github where we'd discuss alternative ways of approaching it, or should we be thinking of this more like comments on a Stackoverflow post (which the 600 char limit seems to imply)?
Ah @MrEngineer13 has gone ahead and rejected it for reasons similar to what I was thinking. This feels very final though - there's no way for me to now comment on this proposal, giving suggestions or expanding on the one rejection comment as to what should go in there.
(I think that was a decent example but certainly I believe a page on Gradle needs more context than just "this is what a Gradle file looks like")
I suppose I should just go ahead and write it myself - that feels like stealing points off rekire though? And then what happens if rekire writes a version that gets approved - would I propose my completely different version as an change?
Sorry for all the questions, I'm just looking for the right way to approach things :)
@AdamS yeah, so you could reject a change but propose a better version that retained attribution. Unlike Q&A, Documentation doesn't care much about the "first" editor (ie. creator) all contributors are more or less equal.
@JarrodDixon's gonna look at allowing comments on rejected changes too
rekire I think that's a good example, but I think if I came looking for the "Layouts" documentation I'd want to know things like: - how can I create a layout? - when would I want to create a layout in code? - what kinds of layouts are available? - how does inflation work? (what is inflation?) Then from there I'd give examples of the different linear layouts, frame layout, relative, etc.
Great Kevin! I tihnk that'll help prevent many back & forth proposal-rejection cycles. I also really like that you can see other peoples drafts when you go to start writing docs for a topic.
so if you end up doing something kind of big (like say all of Layouts), you don't have to fit it all into one page - assuming it makes sense to you to break it up.
For something like the Hello, World page I was thinking you'd need to do something like that - for example it probably makes sense to have a separate page for setting up dev environment.
if you move examples around, or link to new topics (that are created by a draft in the group) it's required they be grouped (so you don't dupe examples or have dead links)
Our rough guideline is "of general use (not so specific it'd only be of interest to a handful of developers), and can be demonstrated in 2-6 examples". I'm sure that's going to evolve over time, like on-topic did for Q&A.
@KevinMontrose Thank you! It feels weird asking for an invite but I think it would be neat to contribute early, and I would be able to help with the java tag as well as copy editing. On my sign-up form I had javascript and html, but from what I've read they are not up yet.
I'll queue you up for one in the coming couple of days, sending invites outside of the waves is a bit manual so it'll have to wait until I have a free moment
I think that's probably too complicated to expect folks to use, though we haven't fought it out internally yet.
Triage for pending bugs and feature-requests is something we're focusing more on now that we're approaching "planned feature"-complete, so I expect that'll get an official answer in the not crazy distant future.
A lot of internal fighting time has been dedicated to rep, which is thankfully settled now.
(until we actually ship it, then we get to deal with community feedback)
Thanks. Well, let's say I wanted to make it anyway (I do). Let's pretend you might want it. Would you have recommended I follow the pattern of the markdown processor you're using for SO now (daringfireball), or would you have recommended a different processor?
I just wrote an example of a topic and the code highlighting worked fine in the preview but after saving it all was gone.
If I try to play with <!-- language: lang-xml -->: The preview brakes totally and will been displayed as empty.
Take this here as example:
http://docs-beta.stackexchange.com...
Those are topics that people think need to be created. They'll be removed from that list when either a) a topic is created based on the request; or b) someone dismisses the request
Your draft is waiting for review right now. If it's approved, the "request" will be completed and removed from the list.
Check that out. Someone approved your draft, so the requests topics list has been updated. :)
Having said that... It seems to me that we should resolve the request when the draft is submitted and restore if if/when the draft is rejected, same as we do with improvement requests. (@KevinMontrose, @JarrodDixon - thoughts?)
Maybe a bug for me too,... I wrote something for android but it is still under "Proposed Change". Is a desired behavior that I can not propose another one in the same topic ?
@Maloubobola Yeah, I think we currently limit you to one pending draft per topic. If you want to make other changes, retract that draft and add them in.
@rekire Not off the top of my head. Report on the site, please?
I want to improve the version table of the Android documentation.
I cannot post it since I get this error:
Release dates for version must be formatted yyyy-MM-dd
Here is my markdown:
Version | API Level | Version Code | Release Date
:------ | :-------: | :----------- | :-----------
1...
I just tried to add a screenshot to an example but the upload button was not visible. Check this screenshot:
