technical writing kickoff

hannesdelbeke commented 1 year ago

Hi and welcome to BQT.

As a start, have a read of the README, and try get familiar with github if you're new to it.
If it still seems like something you are interested in, leave a reply below.
Note that some things might seem too technical, depending on your background, but i'm good at explaining things in layman terms. So happy to take on newer people and help you learn.

Let's see how many people reply on the thread first. If there are several people interested, may I suggest maybe a mentor system? 2 people per PR, someone with more experience who can provide feedback for newer people.

Some rough info:

timeline is flexible
we need a wiki (started putting some rough notes in there)
every feature needs to be documented, and have an example
clear guide on how to adopt bqt
clarify pros and cons of wrapped and unwrapped mode, and other features.
address all issues with the tag documentation
which methods devs should call, and their arguments. which modules to import.
bonus: protected or private methods.

let's start posting in here, maybe a voice chat or discord later. feel free to post any questions

hannesdelbeke commented 1 year ago

easiest would be to work in a wiki branch, and use obsidian to edit the wiki. I can set up an automated build pipeline, so you can submit PRs we can review together
direct access to the bqt wiki doesn't has review, and would need admin approval.

jrex003 commented 1 year ago

Hi, I'm interested in helping. I am brand new to this and do not have a formal software background. However, I can learn fast and willing to receive any feedback and/or guidance (will need some to start).

hannesdelbeke commented 1 year ago

welcome @jrex003 , glad to have you 💪

I ll set up some docs basics for you to start editing.

Meanwhile you will need to instal

git (on windows it's git for windows)
a UI to control git, e.g. Fork (Mac & Windows)

and for text editing we might use Obsidian, unless I get setup with sphynx. but that's a lot more complex to use though.

hannesdelbeke commented 1 year ago

I set up a wiki branch with some placeholders.

This will sound complex, and like a lot, but if you try step by step and google when you get stuckm or ask me, you ll get there. Here we go 🚶: (and don't be afraid of making a mistake, you can't break this project)

you will need to fork the repo with all branches
then clone the forked repo (big green button at the top on the front page)
swap branch to the wiki branch
open the folder in obsidian, and edit the text files
make a single edit, push it to your fork
create a PR, and i should be able to review it.

jrex003 commented 1 year ago

Since Fork is paid only, would Github desktop or Gitkraken work? If not one of these can you recommend a good free one to use?

hannesdelbeke commented 1 year ago

Those work too, there's also sourcetree. Fork has a free demo mode that doesn't expire if you install the paid version.

And don't confuse forking a repo (which is a common git terminology of making a copy of a project) with Fork (a git GUI client, note the uppercase F). A fork is a (linked) copy of a project on Github

hannesdelbeke commented 1 year ago

created more updates to the wiki. which you can find in the wiki branch.

left a lot of #TODO 👷 in the notes. it'd be great if you can have a look at the pages i made and search for the #TODO 👷. a good place to start would be the front page home.md in the chapter features

siolavL commented 1 year ago

Hi, I'm here from Reddit. I'd love to contribute to your project's documentation. I graduated in 2020 with a Bachelor's degree in Technical Communication and have been working on various freelance projects since. I don't have much experience contributing to open-source documentation, but I've learned the basics of Git and GitHub. Your project looks cool (I've been curious about Blender) and I can't wait to get up and running. :)

On Reddit, you mentioned wanting to see some sample documentation:

A Git tutorial that I have been working on. It is not perfect yet, but hope it demonstrates my typical writing style and document structure.
A knowledge base article that answers a common user question.

Please let me know if you have any questions! I will catch up on the activity in this thread and read the project wiki in the meantime.

hannesdelbeke commented 1 year ago

Hi and welcome @siolavL , those samples look great🔥
Glad to have you!

Have a read in the wiki, it should contain some instructions. Try to get a sample PR up and running, once you managed that, you can start improving the wiki. Meanwhile any questions, I'm here.

hannesdelbeke commented 1 year ago

@jrex003 get his first PR #95 up and running 🥳 congratz If you can try the same @siolavL , that 'd be great.

siolavL commented 1 year ago

I'm stuck on the step about opening the files in Obsidian - I have the repository forked and cloned, but unsure which file I'm supposed to open with Obsidian. I've not used it before.

hannesdelbeke commented 1 year ago

first swap to the wiki branch then you have to open the repo folder as a vault. obsidian is basicaly a fancy text editor.

worth noting which step you get stuck on and add it to https://github.com/techartorg/bqt/wiki/tips-for-bqt-doc-writers

jaysnel commented 1 year ago

Hey! Here from reddit and your projects seems pretty cool! My background is in software engineering but looking to move into technical writing so I have a decent history with github. For anyone else who sees, more than happy to help where I can if you have questions!

Looks like I can start with looking at the Wiki and get caught up from there. Looking forward to helping and please let me know if you have any questions!

hannesdelbeke commented 1 year ago

welcome @jaysnel👋 , glad to have someone else who can help out with the technical questions

hannesdelbeke commented 1 year ago

To avoid people working on the same pages, everyone post here which page you are planning to work ⚠️.

When a PR is merged in, you have to sync your fork to get the latest updates in your repo. I just merged in a test PR https://github.com/techartorg/bqt/pull/96 from @siolavL , so everyone else can test out the sync fork already.

siolavL commented 1 year ago

I'll have free time to work on the "contributing to bqt's documentation" page tomorrow. :) The same page I submitted my sample PR to.

siolavL commented 1 year ago

Just an update - throughout the day today and this weekend I will continue to suggest changes to the contribution guide, until the steps are fully clarified.

stacyrch2019 commented 1 year ago

Hi! I'm interested. I have a lot of experience with GitHub as a technical editor and PR reviewer, but no technical writing samples.

hannesdelbeke commented 1 year ago

👋 Glad to have you @stacyrch2019 . If you have GitHub exp, you'll be fine. Have a read in this thread, check out the wiki, and read the brand new contribute guidelines that @siolavL just merged in.

stacyrch2019 commented 1 year ago

Hi hannesdelbeke,

I created a pull request for my initial commit.

https://github.com/techartorg/bqt/pull/104

Thanks,

stacyrch2019

techartorg / bqt

technical writing kickoff #92