technical writing kickoff

[hannesdelbeke]

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]

• 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]

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]

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]

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]

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]

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]

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]

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]

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]

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

[siolavL]

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]

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]

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]

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

[hannesdelbeke]

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 #96 from @siolavL , so everyone else can test out the sync fork already.

[siolavL]

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]

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]

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]

👋 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]

Hi hannesdelbeke,

I created a pull request for my initial commit.

#104

Thanks,

stacyrch2019