Collaborators Wanted!

[briandominick]

This is going to be a big project.

It must have a broad base of participants, or it will be too small or narrow to fulfill the mission of providing a true alternative to this particularly corporate-dominated space.

I don't even want to be in charge of this endeavor, if someone else would like to head it up. I will make sure the tooling is worthy of the content via the sibling Open Styles Project. I will stay involved, but I can think of many people who would be better at leading this one than I would.

PLEASE do not hesitate to leave a message below or come talk in Write the Docs Slack (#style-guides) where I'm about to go post.

[AninditaBasu]

🙋🏽I'd like to be involved, if I may? I was a technical editor for several years at a big corp (though I transitioned back to technical writing), and Style guides are something that are very close to my heart.

[briandominick]

You're quite welcome, @AninditaBasu. I'll post here when there's something concrete like a conference call to schedule, and I'll be adding topics for discussion here in the Issues. Feel free to start any conversations you wish.

[redweezul]

I could help out as well. I've worked as a tech writer, copywriter, editor, and content manager for various clients. Some employed style guides; others didn't, even though it would have helped. Shaping an objective, close-to-universal-as-possible style guide is a good endeavor.

[qua-1]

Hi, I'd like to offer my help to the editorial committee. I could join as a full committee member to start with and then if required at a later date, wind the workload down (or up!). While I'm fairly new to technical writing (two years in September), I moved into it after 14+ years of traditional publishing in the academic, corporate, and B2B sectors. My experience comes from roles including technical editor, project editor, managing editor, copyeditor, copywriter, academic writer, and proofreader. In some of those roles, I participated in style guide development at enterprise level, and I've written modest guides for B2B magazines. I've also delivered training on editing academic journals, and been a copyeditor and proofreader for academic journals, which required me to learn a few different style guides. I'm currently a tech writer (team of one) at a software company in the SaaS sector. I've been developing content ops there from the ground up - including their first product style guide, writing product docs for various audiences, and writing marketing materials (case studies and research blogs). Before all the above I was a graduate front-end coder for about four years. That was just before Web 2.0 (i.e., I was coding HTML 4.1 and CSS 2.0).

[briandominick]

Attn: @qua-1 @redweezul @AninditaBasu

I am so excited to have a handful of people already involved! It sounds like there's some great experience in the group, and I'm honored that you want to give this a shot together. I think if we have a small founding circle to kick things off, it may actually appeal to many more soon.

I've added a Creative Commons license to the repo just to be clear that every bit of work that goes into this from here on out can be forked, so nobody will lose the rights to their contributions (or others') under any circumstance. If there are significant differences in how we proceed, parties are welcome to go their separate ways.

That said, I would like to have a meeting to make sure folks are generally on the same page with our approach. I don't want to add tons of process or structure up front, but maybe we can agree on a general mission statement, a contributors' agreement, and a code of conduct. I'd be happy to adopt some of the excellent boilerplate language that's come out in the last several years. No need to reinvent the wheel. If folks have experience with these things, organizing advice/help could be a great contribution up front.

Do folks already here have availability next week? My schedule is pretty flexible and I am at my desk early and late hours (US Eastern time zone).

[redweezul]

I'm in Pacific time, but am fairly flexible as well. I could meet Tuesday morning (9-7), Wednesday afternoon (9-8), or Friday afternoon (9-10).

[itsdeannat]

I'm also interested! I work in a docs-as-code workflow at my job and manage our content/source-code style guide at my job. I'm in the EST time zone.

[AninditaBasu]

I am in the IST time zone (UTC+5:30) but I can get up as early (or stay up as late as midnight) as needed.

[briandominick]

Wow, we are going to span a lot of time zones. I love it!

I can do any of @redweezul 's time slots. How do they work for others? Say...

7 Sept - btw 4pm - 7pm UTC 8 Sept - btw 8pm - 12am UTC 10 Sept - btw 8pm - 12am UTC

cc: @AninditaBasu @deanna-cs @qua-1

(I think I'll start assuming people are getting notices if they're on this thread.)

[AninditaBasu]

7 Sept - btw 4pm - 7pm UTC

4 PM - 6 PM UTC works for me

8 Sept - btw 8pm - 12am UTC

no 😴

10 Sept - btw 8pm - 12am UTC

no 😴

(I think I'll start assuming people are getting notices if they're on this thread.)

👍🏽 I did

[qua-1]

Hi all,

Excited that we'll be meeting so soon. I'm in Scotland, UTC+1 at the moment (will be UTC +0 from 31 October, when we switch into daylight savings time).

7 Sept - btw 4pm - 7pm UTC: Yes, this works for me and is the best option for me.

8 Sept - btw 8pm - 12am UTC: Yes, but would have to finish before 10pm UTC.

10 Sept - btw 8pm - 12am UTC: As above (finish before 10pm UTC).

Simone Hutchinson Editor Professional Member of the Chartered Institute for Editing and Proofreading LinkedIn: https://www.linkedin.com/in/simone-hutchinson/

On Fri, 3 Sept 2021 at 05:41, Anindita Basu @.***> wrote:

7 Sept - btw 4pm - 7pm UTC 4 PM - 6 PM UTC works for me

8 Sept - btw 8pm - 12am UTC no 😴

10 Sept - btw 8pm - 12am UTC no 😴

(I think I'll start assuming people are getting notices if they're on this thread.) 👍🏽 I did

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/DocOps/freestyles/issues/1#issuecomment-912250277, or unsubscribe https://github.com/notifications/unsubscribe-auth/AULFMJAFGEGFQIH4QNGN4XDUABGYZANCNFSM5DCMY36Q . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.

[CollierCZ]

I'd be happy to help with putting things together and reviews and such, though I'm not sure I'd be the most help in the initial organization phrase.

[briandominick]

I'm going to go ahead and proposed we meet 7 September at 4pm UTC (so noon EDT, 9:30 (?) for Anandita, and 9am PDT).

Does anyone have a Zoom we can use? I default to Jitsi for meetings otherwise, which is pretty good for small groups.

[redweezul]

Sounds workable to me. I don't have a Zoom though.

[camerons]

Hey Brian, have you noticed that the Microsoft Style Guide is shared under a Creative Commons Share Alike license? https://github.com/MicrosoftDocs/microsoft-style-guide/ Have considered just forking it? I suspect if we ask nicely (and wait a year for processes to move) that the Google Style guide could be released under CC-By as well. Also, I notice that are are proposing CC-By-NA. This would put legal barriers in place for a future integration of Microsoft/Google/Your style guides, which I think would be a good thing. I suggest using a CC-By instead.

[camerons]

PS, a year or two ago we collated a bunch of things needing fixing in tech writing, and steps to get there. It includes a section on a style guide with ideas similar to what you are proposing.

[briandominick]

Actually that's very interesting, Cameron, re the MS and Google style guides. I had thought it was the exact opposite. Here's why:

On MS's front page, they have © 2021 Microsoft. All rights reserved.

Whereas Google's front page has:

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

In any case, I'll remove my snarky remark in the README about big corporations coming after you if you reuse their stuff. Very uncharitable of me -- at the time I thought both were copyRight.

Re the license, I think where you said CC-By-NA, re the license I've porposed, you meant CC-By-NC, which is the noncommercial version. I'm happy to discuss the use cases, and maybe I'm misunderstanding the license, but I thought NC just meant you cannot sell our content down the line, just as we are not selling it now. It does not mean you cannot reprint our style guide without selling it or use it in a commercial setting -- you just can't reprint it as part of something you sell, which I don't know a use case for. It would allow MS or Google to reprint it in their guide but would not let them sell the guide. Which, why should they get to sell something that we did the work for?

I would be happy to kick this project off by forking either or both of these guides. It should definitely be on the table.

The Google Doc you shared is a treasure trove. Thank you!

[briandominick]

I haven't heard back from everyone re the time, but I'll be in this video conference at 4pm UTC on Tuesday: https://meet.jit.si/docops-freestyle-guide-initial-meeting

cc @AninditaBasu @deanna-cs @redweezul @qua-1 @CollierCZ

[camerons]

Yes Brian, I was recommending against CC-By-NC. Good to see that both Google and MS have CC-By content. That will make things easier. Maybe the real value you can provide is:

• Create an aggregate MS and Google style guide, which picks the best from each, and points back to both points of truth so that users can decide which they prefer.
• This would involve auditing both guides.
• You would want a process for triggering updates when ever the source guides are updated. (I'm aware the Google guide updates regularly, and suspect the MS guide updates regularly too.)

It would be worth reaching out to both Google and Microsoft to see if they can collaborate to some extent. (At the very least, let you know when there have been updates.) If interested, I can look up some names of people.

[MattDodsonEnglish]

I think a big challenge of this project would be creating a set of global guidelines that people could agree on. I had two ideas about this.

1. Perhaps at the beginning, you could focus on the lowest hanging fruit. E.g. is there any controversy that ordered sequences should use numbered lists instead of unordered ones?

2. Alternatively, rather than perscribing these particulars, perhaps this project could aim to be a more of a meta-styleguide. Rather than saying, "Write parameter examples in monospace font", it might be more useful to just lay out that example parameters are a distinct semantic class. Then you can let the writer define how they can mark that class up--maybe specify sensible, standard defaults e.g. monospace.

In my experience, until they find out about them, most people are not even aware that these little distinctions even exist. Similarly I often look at the Microsoft and Google "Describing UI element" sections, not because I care so much about Google's precise term, but rather because I just want to see how experts have defined the elements of UI, and see whether there's a known entity for "that box thing with the buttons."

[briandominick]

Following up on all of this...

Yesterday several of us had a meeting that ran about an hour. We mostly discussed:

• Broad goals of the project
• Relationship to Good Docs Project

I thought the meeting went well, and the interest seems somewhat sustainable, or at least a solid seed for something ongoing. We did not try to scope anything out or estimate what it would take to really dig in on this project, but it seems like a GDP working group setup makes a lot of sense. GDP chair @barbaricyawps was present at the meeting and extended a fairly broad and very warm invitation to participate, and the rest of us were inclined to pursue that.

I wanted to post this update just in case anyone at the meeting was uncomfortable raising objections, or anyone who was not present. Anyone is welcome to get in touch with me privately or post here with any concerns. Barring that, it looks like our next step will be to take this into GDP auspices. I am pleased to have kicked this off and will be happy to be part of any group that wishes to pursue an independent TW style guide.

It does seem to make sense to go with the CC-by for reasons @camerons expressed. All that input is appreciated. I'll make that change.

On the other matters raised by @camerons and @MattDodsonEnglish: I appreciate all of this sound advice. I think starting with a baseline, and using a process that yields increasingly useful results starting very early is the wisest approach. I think there might come a time when it will make no sense to stay downstream of the Google or MS guides, but there are surely ways to add value early and continuously.

[camerons]

Hey @briandominick, do you have an update on how you see this project moving forward?

Are you still wanting to create a Good Docs Working Group? And if so, would you like a hand setting it up and setting up a periodic meeting checkin?

[briandominick]

Thanks for checking up, @camerons. I am afraid my attention is spread across too many repos and projects at this time, so I do not have the bandwidth to carry either of these projects any farther until I wrap up other loose ends. To the extent clients of mine wish to sponsor aspects of this, I will definitely be pushing commits back to the Open Styles repo.

As much as I wish to see an alternative to the status quo around style guides in the tech space (and beyond), I am going to have to hope somebody else figures out how to move this forward. I am less likely to find sponsorship for an adaptable general style guide for the tech space, but I bet there are companies or foundations out there that would back such an effort specifically as an independent project.

If anyone has initiative to take this in any direction, I would do what I can to support you. I don't feel ownership over the idea for FreeStyles, or even any particular implementation of the concept of OpenStyles, which I'll probably pursue while serving my next few enterprise clients, since most orgs default to picking an upstream guide and really just need a way to maintain their local supplement.