To improve visibility of ongoing Docs projects and where to get help with onboarding and Docs authoring tools, I would like to make a gentler step for Comms plan.
LinkedIn Technical writer group: I joined technical writing working group (50000 members) in Linkedin to engage with pros working with documentation and new people wanting to learn about technical writing.
Medium technical writing group: Medium has passionate tech writers and influencers. I have been writing for Medium since 2021.
Red Hat Summit: Connect EMEA: I attend local London Red Hat event every year. Next one is in November 7. It is a great opportunity to get to know developers, solution architects, and sys admins who manage documentation as part of daily routine and user support. The vast majority coming to the event knows Fedora.
What else can we do to reach out to right people outside and inside Fedora?
I see there’s a conference in Melbourne, Australia in December — any docs-interested locals want to go and represent? (Or Portland, Oregon next April?) Of course, it doesn’t need to be conference-centered, but if it is convenient for someone that might be a good way to build bridges.
As far as the Marketing Team is concerned, I think regular pings from you guys on what is going on in Fedora Docs (besides this ticket with ideas) will be good to keep Fedora Docs in the mix of social media coverage. The more we’re talking, the more we keep the ideas flowing for new ways of pointing people to your team.
If you ask me, I’d sprinkle the topic over monthly workshop and get feedback from attendees.
Afterwards, video clip can be edited and posted to social channels.
How do we publish Docs?
Behind the scenes: FOSS tool chain
How to make presentation with AsciiDoc?
How to use prose linter to ensure Docs are written to style guide
Git for writers
Team shared doc using Etherpad widget in Matrix Chat
In all honesty, talking ‘about’ documentation could be awfully vague. However, if we turn that into hands-on Docs session like cooking class, it will be more useful.
Have we thought about how to encourage the Fedora contributors who work on their specific areas to also contribute docs for what they work on? For example, does the Workstation WG contribute to Workstation docs? If not, what can we do to encourage them to do so for their stuff?
Once our new Operations Architect gets up and running, this may be one of those areas where she can help us on process. Maybe Fedora Docs is something that needs to be integrated into the release cycle more?
As far as I can tell, user documentation of each working group is maintained individually and it is edition-specific.
For example, continuous improvement of server Docs or IoT Docs is an agenda of each WG.
I can’t add much here because my involvement with Docs is edition-agnostic.
Release notes appear to be integrated into the release cycle.
An important question to ask is who are you trying to reach and why do you want to reach them? A comms plan is important, but I would start first with what message you want to craft and who you want to craft it to.
For example, are you trying to attract more technical writers? Then, messaging about opportunities to write in Fedora (e.g. Quick Docs, Edition docs, etc.) are good to highlight. These people might want to know about the “product” being documented and how they can familiar with it. Extra focus could be given on tooling and workflow, because this audience may not be as comfortable with certain docs workflows.
Are you trying to attract developers and designers? Then, messaging about our tool chain, how we use Antora, and how things get published are good to highlight. These people might want to know where our key repositories are, what opportunities there are to take on new work, and how their changes would get accepted and deployed. Extra focus could be given on connecting with the Websites & Apps Team if needed, so this audience can connect with a developer group beyond just Fedora Docs.
Are you trying to attract students and open source newcomers? Then, messaging about Fedora generally as a project and making the very first steps are good to highlight. These people might want to know how they can get hands-on, where they can find info and docs about our tools and our processes, and clear instructions for a first task. Extra focus could be given on the newcomer experience via “good first issues.” That is to say, more work might go into getting their first contribution into Fedora Docs than the work required to complete the Docs in the first place.
Each of these different audiences means different kinds of outreach. You write different things for different kinds of people. What you write would go to different kinds of places, like the various links shared earlier in this topic.
I think this is a historical pain point. Some of tried and failed to bring things closer together. I know (from my experience) that @amoloney will be in full “listen and absorb” mode for a while, but this might be a mid- to long-term challenge to think about how to give Fedora Docs more priority in the release process. My hypothesis is that it is likely a two-way street of changes needed on both sides to get a better process that works for everyone.
Workshop program covers top priority tasks that are depending on various issue tickets in Quick Docs, looking for document writer and reviewer. This is fundamental requirements to build the Docs community. If we need to expand our focus to UX designers too, you need to involve other work groups.
Once we keep momentum going through 2024, we could then extend campaign target to UX designers as well as new comers.
That makes sense. We can probably follow any additional communications with a focus on specific Quick Docs tickets or tasks that a writer audience familiar with Linux could help with. Does that make sense?
With that in mind, I have included target audience on the workshop agenda. Reaching out to right audience will require consistency and engagement by interest of the group.
Write the Docs community
The Write the Docs community has 9000 members in their Slack ‘Workspace’, which has about 15 channels. Under that channels, I have found interesting ones such as AsciiDoc, learntechnicalwriting, staticsitegenerator, localmeet and so on. I’m on ‘read’ mode mostly and try to help out wherever I can.
We could combine social media messaging with thoughtful engagement (DM and group chat).
Connect with top writers on software documentation
The other method is to connect with top writers in technical writing community.
GitLab Docs team
I shared my first impression on WebIDE on GitLab issue board in April 2023. One of lead developers of GitLab re-posted my tutorial video (it is really primitive uncut screen recording) to LinkedIn and Twitter. They are happy to talk to us for an interview.
I’d say there are many invisible contributors on Docs communities. Docs is one of few domain that can flourish without in-person interactions.
That was one of my main thesis of my talk on Flock this year. And I have various targeted measures in mind to strengthen and improve the integration of documentation and (technical) development. This will be a difficult process, I expect, and will require a lot of work to convince (technical oriented) community members. But the first step has already been taken.
In fact, this is a key element. I talked about that on Flock this year as well. Perhaps we have not taken this into account decisively enough so far.
The idea I put forward in Cork (or at least wanted to put forward, maybe it got lost in the technical issues) is to appeal to the typical Fedora user and encourage them to contribute to Docs. My catchphrase for this is: “Share your experience and knowledge” - in emphasized offset from “authors” and experts in writing texts. I want to address “everyone”.
The aim is to propagate the possibility of making one’s experience available to everyone, to a certain extent on the side and “while in the current way”. And Quick Docs and the web interface are particularly well suited for this (at least that’s the idea). Perhaps we need to focus the comms plan even more on this.
What do our “comms plan experts” have to say about this?
And to the other aspect: Improved integration of technical development, which was another of my main thesis in Cork.
Yes, that is it. And I already took a first step “in the background”, when I initiated the automatic creation of the release notes from the change proposals. And I had an insightful discussion with FESCO about making certain documentation requirements mandatory, in the same way that certain technical requirements are mandatory (this would be a key element). To summarize: There is still a long way to go. But we are on the go. And the next step is to improve this automatic process and find allies for decisions.
Can you think of anything about this? Specifically allies?
It used to be, very long ago. We kind of un-integrated it during a period where the docs team was not healthy and it was causing strain on both the team and the release itself. But we shouldn’t leave things stuck at where they were at a low point.
Is there anywhere some information about that process and the issues that caused it?
The first time I contributed to Fedora Docs it was FC1 and the following 1-2 years. There was an integration, probably simply because Fedora was not as highly differentiated back then as it is today.
To keep things simple, light and manageable, I would suggest using Matrix and Fedora Join as a main channel of interactions and communication for new comers and contributors alike.
Matrix chat Docs room: lots of interactions happen in this official Fedora chat.
Fedora Join/Welcome-to-Fedora
(Discourse for announcement/shaping ideas)
In addition to the above channels,
Periodic news update in CommBlog and share it on social media by marketing-team - thanks in advance
Writing workshop
Engagement with tech writer community: Write the Docs
