Qmk_firmware: Documentation: Update the guide for handwiring

[skullydazed]

Our hand wiring guide is outdated and should be touched up and added to our documentation site.

https://github.com/qmk/qmk_firmware/blob/master/docs/hand_wire.md

[4sStylZ]

If you want some inspiration : https://imgur.com/a/qcgdF

[fredizzimo]

That imgur link is actually a copy of this geekhack.org thread

[Gouty]

I'll take a crack at this

[Gouty]

I made a good start to this, and I'm trying to combine the best bits of the community guides that are available.

Unless anyone says otherwise I'm going to hide all the in depth description about how a keyboard matrix works in <details> tags as it's not strictly needed to why it's done that way, just how.

Is there any way I can add images to this guide? I notice that images are listed in the .gitignore file, can I modify it or will it just be immediately rejected (and will it play nice with qmk.fm?)

[drashna]

For images, hosting them on imgur or the like works.

[Vexatos]

I'd suggest hosting them on github along with everything else. Having images specifically be hosted elsewhere would add dependency on another external website with little control over the file, and it would make a lot more sense for everything to be in one place; it would also subject the images to version control like everything else, meaning they too can be tracked.
Perhaps images inside the docs/ directory could be explicitly whitelisted in the .gitignore? And then have the files in some images/ subdirectory, that way they can be directly referenced from the markdown files using relative paths. That should be a much better solution.

[jackhumbert]

We used to have images in the docs and in keyboard folders, but they significantly contributed to the repo size, which was painful for people just downloading the source code. A semi-permanent hosting service like Imgur is our official recommendation for keyboard-related ones, but files can also be added to qmk.fm in a tandem PR. I think the latter would be appropriate for something like this, or any image needed in the docs. It may also be appropriate to put the guide itself on qmk.fm, or qmk_hardware (which could probably be fleshed-out a bit).

[Vexatos]

Might it make sense to have a separate github repo for images? Although that could be even more confusing.

[noroadsleft]

I actually have a repo I started because I had this very same issue of needing to include an image on something in qmk_firmware, but not wanting to actually put the image in qmk_firmware. (I agree strongly with the guideline of not allowing images in qmk_firmware.) Imgur works, but as has been said, it's an external dependency, and also doesn't version track.

I work with my repo mirroring the folder structure of qmk_firmware just because it makes sense to me to do it that way, which lowers the cognitive load of trying to figure out where an image is being used.

I wouldn't mind transferring ownership of that repo to QMK if it's something we decide would be good to do.

[rishav142k]

I think it makes sense to have a completely separate repo just for hosting the images. That way, people downloading the source code won't have to deal with them.

[Gouty]

By that logic, doesn't it make sense to have all the ancillary stuff (such as this documentation) as part of that separate repo? Or a wiki?

[yanfali]

@Gouty no, because then it would probably fall out of sync. When you check out the repo, you get the latest documentation.

[Gouty]

Surely people are checking the website for the documentation (the content
for which is automatically updated from this repo)

On Mon, 7 Oct 2019, 18:46 Yan-Fa Li, [e-mail] wrote:

@Gouty https://github.com/Gouty no, because then it would probably fall
out of sync. When you check out the repo, you get the latest documentation.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/qmk/qmk_firmware/issues/1686?email_source=notifications&email_token=ADA7U3RP3RYJCHCJHT23GL3QNNYX5A5CNFSM4DZ2RFPKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEARGX6Y#issuecomment-539126779,
or mute the thread
https://github.com/notifications/unsubscribe-auth/ADA7U3QAXKIIZ7CQH6M53ALQNNYX5ANCNFSM4DZ2RFPA
.

[yanfali]

@Gouty I think you just answered your own question. It's generated from a single source of truth and it comes bundled with the project. Having two projects would remove this property. DRY (don't repeat yourself)

[helios1101]

As I was explorinng the docs, I personally felt that everything has been bundled up at a single place, as images and important docs should be particularly in different places. Or either it may be, docs having a transverse relation to images must be at a separate place.

[noroadsleft]

One reason that I'm personally against splitting the docs into a separate repo is that changes to core functionality (new features, extending/modifying existing features) often requires changes to the docs. Having them in the same repo means this can be done all at once in a single PR (excluding any need for images, obviously).

[thiagoyeds]

Among the options discussed here, I would choose to keep in the same repository and make use of the wiki.

[jasonappah]

Regarding the issue of images making the repo larger, would Git LFS solve the issue? That way, the images are still being versioned and can be edited, but they aren't being stored on GitHub. The tutorial I linked explains it way better than I have.

[vaibhavbisht06]

Is there any way I can add images to this guide

[4sStylZ]

Yes you can upload some image on imgur and use the markdown ![picture-name](url) syntaxe to show them or, like somebody that I can remember upload them on another git repo and relate to them with the same syntaxe.

I suggest external link because it's not recommanded to upload image on the repo because this will increase the size of it to much.

[ShiftyBlock]

We should keep the guide in the same repo since splitting up requires relinking and reconnecting everything, less work

[stale[bot]]

This issue has been automatically marked as stale because it has not had activity in the last 90 days. It will be closed in the next 30 days unless it is tagged properly or other activity occurs.
For maintainers: Please label with bug, in progress, on hold, discussion or to do to prevent the issue from being re-flagged.

[skullydazed]

Addressed by #7044.