cbeams
commented
4 years ago Transcribed from conversation between @cbeams and @kemmcall in Keybase #introductions channel beginning on Fri 2020.03.06:
9:44 AM - Fri kemccall joined #introductions.
kemccall 9:54 AM - Fri Howdy! I'm a professional technical writer in software development (but also have a hardware background from way back when) and been down the bitcoin rabbit hole for the last 18 months or so. I'm philosophy-wise Cypherpunk to the core.
To put me in perspective I've been in the computer realm since the DEC PDP series mini-computer days.
I'm C4 Certified BTC Professional (which probably nobody has heard of), but none-the-less it seemed to be an Andreas Antonopoulis sanctioned "thing" and at least verified (if only to myself) a degree of competency and knowledge.
I'm desperate to NOT do my next BTC buy from an exchange and as anonymously as possible, and come to the conclusion that as one organizations says, "friends don't let friends sell bitcoin".
I'm huge on privacy and anonymity (as I'm sure most are here -- go eff.org!). After all, the whole bitcoin concept is electronic cash. So, the Bisq ethos I'm totally behind! It's amazing conceptually and in implementation. I'm just beginning to get my head around it.
I noticed that the section, "Staying Private — Maximize control over your personal info and trading data" has no information, so I may very well be interested in contributing in this documentation area -- once I become more knowledgeable.
So, for now, cheers!
cbeams 2:33 PM - Fri Welcome, @kemccall! We could certainly use a solid technical writer. Can you point to any public work you've done? I'd be interested to have a look and talk with you about potential ways you could contribute.
kemccall 1:24 AM - Sat Fun stuff that I'm beginning to pick up on again after a long hiatus: https://medium.com/privateria-info and https://medium.com/the-chortle-portal
kemccall 1:25 AM - Sat Ken_McCall_Resume_Technical Writer_030620.docx
kemccall 1:26 AM - Sat What pays the mortgage (above).
cbeams 12:48 PM - Sat @kemccall, would you be interested in doing editor work on our new MediaWiki instance at https://bisq.wiki? Quite a bit of content has been coming together there over the last weeks, and the general plan is to migrate the content currently at docs.bisq.network to the Wiki, but much of it will change in its form and style in the process. I put together the following screencast last week to begin laying the foundation for the structure and approach we'd like to take. Perhaps you'd like to watch it and see if this is work you'd be interested in.
keybase://team/bisq/2020-02-26%20Wiki%20structure%20and%20categorization%20screencast/zoom_0.mp4 You can also have a look at the issue and board for the project to "Roll out the Bisq wiki". This will give you a sense of what's already been done, and what remains. Note especially there the task to "Create Wiki Editor role". It's this role that I'm suggesting you might be interested in.
Project issue: https://github.com/bisq-network/projects/issues/8 Project board: https://github.com/orgs/bisq-network/projects/14 "Create Wiki Editor role" issue: https://github.com/bisq-network/admin/issues/53
Have a look and let me know what you think. We can discuss further if indeed you're interested.
kemccall 4:14 PM - Sat Cool. I’ll check them out. Deadlines or needed timeframes?
cbeams 8:19 PM - Sat Not really, @kemccall, as this would be ongoing work. There would be a push up-front to establish some conventions, get existing content in order, transcribe / adapt existing content from docs.bisq.network to the wiki, etc., but what we ideally want is one or more people who can take on this editor role and be available to review and edit changes to the wiki as they come in. Writing new content yourself is also welcome, but that is distinct from the editor role we're talking about here.
If this is something you want to dig into, it would just be good to know roughly how much time you think you could spend on it per week. We could prioritize things from there.
kemccall 3:58 AM - Sun Chris, sure, I'll step into the editor role. It actually seems like a perfect time, as it seems you're just getting started. I watched your vid. Your basic structure (taxonomy) is a good start and writing concepts good. I wouldn’t worry about adding more high-level categories - they will become apparent as the system develops. But, I d recall some wikis have weirdly issues with file renaming and taxonomy restructuring.
You’ve set a standard for styles which is great. So, the only styles I would documenting in the Bisq wiki would be any exceptions to the Wikipedia styles (I think that’s what you said you were using). And the visual style issues are easy to teach people about.
Of course style also applies to the grammar. While many wikis have a very conversation tone and American colloquialisms, these are more challenging to an international audience and thusly translations.
You’re starting to deal with basic tech pubs / information architecture issues. The issue you mentioned about trying to determine what a media wiki file should consist of, is dealt with in a number of ways. It’s the content structure that is more challenging.
In general, all (ok, maybe 95%) information will fall into one of three general types - concepts, tasks (procedures), or reference material. What all tech writers know is that you don’t mix them up. That is, for example, if you write a procedure you don’t mix in conceptual material. Granted, a bit of conceptual info may at times be necessary to move someone along in a procedure, but the point is you wouldn’t use that procedure as the source for your reference information. Same for the other types. This eludes to the concept of topic based documentation, and at a deep level content reuse.
More issues arise when determining what exactly the end result should be. For example, will the output only be the wiki, or will you also want people to also be able to create PDFs? You may also want to use the media wiki topics as help topics for the application. These issues play a role in file (topic) content.
I’ve used a number of wikis in the past (Confluence currently) but I’ve never more than dabbled in Mediawiki, so I don’t know how well Mediawiki can cater to a help system. I’ll spend at least a few hours delving into Mediawiki’s capabilities, and more importantly limitations.
You mention use-cases a number of times and I think what you really means is the end result of a use-case. That is, a use-case may be, “we need a widget with certain characteristics” (a description used to develop the feature). The end result, from a document standpoint, is a document (topic, guide, etc) that describes the widget which has become a feature or something. In other words, a tech writer wouldn’t call a document a use-case, even if we were documenting a use case. However, the term use-case isn’t something a casual user would understand. It’s pretty much in the developer realm.
As you eluded to the topic descriptions are critical to the end user and search utility.
One style that is beneficial is to adopt gerunds (...ing) for procedures. For example, “downloading and installing”. But, again it is a stye issue.
A major issue in wikis is governance. And I notice in Mediawiki they have something called Patrolling. Which seems perhaps more fore the coding world than grammar, but I confess to not completely understanding it. What I think is critical is for the wiki to be moderated. That is, you can have anyone add or modify content, but before that content gets published someone with real skin ion the game looks at it first, and may modify it, or maybe not even include it.
Having created a number of Wordpress blogs, I can tell you in short order people start putting garbage in your wiki.
Anyway, that’s all for now. It’s hard to tell how much time I can spend, I would estimate 3 hours per week, maybe more during what I consider this start up phase. Because I’m in the software development world, in my world, we have 3 major releases per year and as we get near the end of any release it become manic. I also have kids.
So, if what I’ve saids agrees with you, let me know how you’d like t proceed (or perhaps not).
To own the patrolling process (bisq-network/wiki#11), the style guide and adherence to it (bisq-network/wiki#9), etc.
Might be initially owned by @m52go, but should be labeled
help wantedand possibly announced as such indicating that we want someone to own this more fully.UPDATE 2020-03-09: @kemccall has expressed interest in this role. I'll transcribe our Keybase conversation in comments below, and am now adding the task list that follows.