Re: [AI] New ORES FAQ

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: [AI] New ORES FAQ

Gergo Tisza
Hi Sarah,

thanks for working on this!

On Tue, Nov 21, 2017 at 2:31 PM, Sarah R <[hidden email]> wrote:

> Documentation like this is critical for our open software environment to
> work.  I'm organizing a special interest group[4] to address
> documentation needs. If you have any questions or comments, please dont
> hesitate to reach out and share!
> [4] https://wikitech.wikimedia.org/wiki/SIGDOCS
>

Is there any particular reason to do it on wikitech? Most of the other SIGs
[1] and most of our documentation is on mediawiki.org (which is in general
a better maintained place). The ORES docs live there too, apart from a few
pages that are concerned with operations issues.

[1] https://www.mediawiki.org/wiki/Special_Interest_Groups
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: [AI] New ORES FAQ

Aaron Halfaker-3
Rainbow colors!  Here's a plain text one for those who can't read the fancy
colors:

Hi Everyone,

I've been working together with Adam and Aaron from the Scoring Platform
team to identiy technical documentation in need of improvement. This past
quarter, the team and I worked together on a FAQ for ORES[1], which is now
up and running.  If you are interested in ORES, AI, or technical
documentation in general, ORES documentation is a great place to contribute.

We've got answers for most of the common questions, but we haven't finished
100% yet.  You can help us by asking new questions on the discussion page
for the FAQ[2]. I hope you can join us in editing BOLDly[3] by working on
documentation that makes our projects more accessible and easier to
understand.

Documentation like this is critical for our open software environment to
work.  I'm organizing a special interest group[4] to address documentation
needs. If you have any questions or comments, please dont hesitate to reach
out and share!


[1] https://mediawiki.org/wiki/ORES/FAQ
[2] https://mediawiki.org/wiki/Talk:ORES/FAQ
[3] https://en.wikipedia.org/wiki/Wikipedia:BOLD,_revert,_discuss_cycle
[4] https://wikitech.wikimedia.org/wiki/SIGDOCS


With much Kindness,

Sarah R. Rodlund
Senior Project Coordinator-Product & Technology, Wikimedia Foundation
[hidden email]
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: [AI] New ORES FAQ

Aaron Halfaker-3
In reply to this post by Gergo Tisza
Gergo,

I thought Wikitech makes sense for a wikimedia-specific initiative.  Now
that you point it out, I'm all for going to mediawiki.org is everyone else
is already there.  Should be easy to move the landing page.

-Aaron

On Tue, Nov 21, 2017 at 5:40 PM, Gergo Tisza <[hidden email]> wrote:

> Hi Sarah,
>
> thanks for working on this!
>
> On Tue, Nov 21, 2017 at 2:31 PM, Sarah R <[hidden email]> wrote:
>
>> Documentation like this is critical for our open software environment to
>> work.  I'm organizing a special interest group[4] to address
>> documentation needs. If you have any questions or comments, please dont
>> hesitate to reach out and share!
>> [4] https://wikitech.wikimedia.org/wiki/SIGDOCS
>>
>
> Is there any particular reason to do it on wikitech? Most of the other
> SIGs [1] and most of our documentation is on mediawiki.org (which is in
> general a better maintained place). The ORES docs live there too, apart
> from a few pages that are concerned with operations issues.
>
> [1] https://www.mediawiki.org/wiki/Special_Interest_Groups
>
> _______________________________________________
> AI mailing list
> [hidden email]
> https://lists.wikimedia.org/mailman/listinfo/ai
>
>
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: [AI] New ORES FAQ

Gergo Tisza
On Tue, Nov 21, 2017 at 4:20 PM, Aaron Halfaker <[hidden email]>
wrote:

> I thought Wikitech makes sense for a wikimedia-specific initiative.
>

A documentation SIG is not really Wikimedia-specific though (or did you
mean "ORES documentation SIG" specifically?).
Also, most Wikimedia-specific technology initiatives are on mw.org (all the
Audiences projects, for example).

Wikitech was originally a place for ops documentation. (It has its own
infrastructure and deploy cadence, so it's unaffected by most failures;
also it's small enough for static HTML dumps. When the site is down and you
are scrambling to bring it back, it's a good thing when your operations
docs aren't also down.) Later Labs needed a management interface which got
tucked onto Wikitech (this was one of those "do everything inside
MediaWiki" eras), so it made sense to put all Labs-related documentation on
wikitech as well. Most other things are on mediawiki.org. There were
various proposals over the years to change that (move wikitech content to
mediawiki.org, move all WMF stuff to wikitech, move all WMF stuff to meta,
move all non-MediaWiki-documentation stuff to a new developer wiki etc.)
but none of them gained much momentum.

Due to being managed differently, wikitech is not a great work environment
IMO. There is no unified login, no page translation support, no structured
discussion support, no pageview metrics, the registration process is tied
to creating LDAP and shell accounts... There are plans to improve this
eventually [1], but between that and the audience differences, I'd stay
away for now.

Btw you are probably aware of the past discussion on a documentation SIG,
but just in case: [2]


[1] https://phabricator.wikimedia.org/T123425
[2] https://phabricator.wikimedia.org/T156301
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: [AI] New ORES FAQ

Aaron Halfaker-3
https://commons.wikimedia.org/wiki/File:Salmo_trutta.jpg

Please stay on topic.  This thread is about the ORES FAQ.  If you would
like to debate about Which Wiki Is The Right Wiki for SIGDOCS, please start
a new thread.  I'm sure Sarah will be happy to discuss the initiative and
its history in that thread.

On Tue, Nov 21, 2017 at 7:49 PM, Gergo Tisza <[hidden email]> wrote:

> On Tue, Nov 21, 2017 at 4:20 PM, Aaron Halfaker <[hidden email]>
> wrote:
>
>> I thought Wikitech makes sense for a wikimedia-specific initiative.
>>
>
> A documentation SIG is not really Wikimedia-specific though (or did you
> mean "ORES documentation SIG" specifically?).
> Also, most Wikimedia-specific technology initiatives are on mw.org (all
> the Audiences projects, for example).
>
> Wikitech was originally a place for ops documentation. (It has its own
> infrastructure and deploy cadence, so it's unaffected by most failures;
> also it's small enough for static HTML dumps. When the site is down and you
> are scrambling to bring it back, it's a good thing when your operations
> docs aren't also down.) Later Labs needed a management interface which got
> tucked onto Wikitech (this was one of those "do everything inside
> MediaWiki" eras), so it made sense to put all Labs-related documentation on
> wikitech as well. Most other things are on mediawiki.org. There were
> various proposals over the years to change that (move wikitech content to
> mediawiki.org, move all WMF stuff to wikitech, move all WMF stuff to
> meta, move all non-MediaWiki-documentation stuff to a new developer wiki
> etc.) but none of them gained much momentum.
>
> Due to being managed differently, wikitech is not a great work environment
> IMO. There is no unified login, no page translation support, no structured
> discussion support, no pageview metrics, the registration process is tied
> to creating LDAP and shell accounts... There are plans to improve this
> eventually [1], but between that and the audience differences, I'd stay
> away for now.
>
> Btw you are probably aware of the past discussion on a documentation SIG,
> but just in case: [2]
>
>
> [1] https://phabricator.wikimedia.org/T123425
> [2] https://phabricator.wikimedia.org/T156301
>
> _______________________________________________
> AI mailing list
> [hidden email]
> https://lists.wikimedia.org/mailman/listinfo/ai
>
>
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: [AI] New ORES FAQ

Bryan Davis
In reply to this post by Gergo Tisza
(dropped ai@ from the CC)

On Tue, Nov 21, 2017 at 6:49 PM, Gergo Tisza <[hidden email]> wrote:
> On Tue, Nov 21, 2017 at 4:20 PM, Aaron Halfaker <[hidden email]>
> wrote:
>
>> I thought Wikitech makes sense for a wikimedia-specific initiative.
>>
>
> A documentation SIG is not really Wikimedia-specific though (or did you
> mean "ORES documentation SIG" specifically?).

Sarah is working on technical writing projects related specifically to
ORES and Cloud Services this quarter (and hopefully for many more
quarters to come). This work is part of the "technical community
building" program from the Technology department's annual plan [0].

Sarah can jump in to say more, but my understanding is that the
initial work of the SIGDOCS is intended to be focused pretty narrowly
on ORES, Cloud VPS, and Toolforge. That certainly does not mean that
we do not have other documentation gaps (we do) or that others are
barred from organizing to work on things like MediaWiki API docs (they
are not). It does mean however that we are making choices about focus
with the hope that this will help make more actionable plans about
which docs to work on first and what sort of work to do.

> Also, most Wikimedia-specific technology initiatives are on mw.org (all the
> Audiences projects, for example).

Where the tracking page for SIGDOCS lives is probably the least
important issue related to organizing the group, but I think your
point is well taken.

> Due to being managed differently, wikitech is not a great work environment
> IMO. There is no unified login, no page translation support, no structured
> discussion support, no pageview metrics, the registration process is tied
> to creating LDAP and shell accounts... There are plans to improve this
> eventually [1], but between that and the audience differences, I'd stay
> away for now.

All of this is true, but then also very false when you learn that
improving the Cloud VPS and Toolforge docs is at least 50% of the
project to be undertaken.


I'd like to second Gergo's initial enthusiasm about Sarah stepping up
to help organize work on documentation. She has a great background in
technical writing as individual contributor and experience in teaching
writing related topics that I hope we can all leverage to get better
at the craft of making clear and useful documentation.


[0] https://meta.wikimedia.org/wiki/Wikimedia_Foundation_Annual_Plan/2017-2018/Draft/Programs/Technology#Program_4:_Technical_community_building
> [1] https://phabricator.wikimedia.org/T123425

Bryan
--
Bryan Davis              Wikimedia Foundation    <[hidden email]>
[[m:User:BDavis_(WMF)]] Manager, Cloud Services          Boise, ID USA
irc: bd808                                        v:415.839.6885 x6855

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l