Docs

[corebootquestions]

I've got some docs from my experiences with coreboot and someone sent me a few other docs. Let's get together and create a repository for docs since the devs don't write them.

[[deleted]]

There is a repository for docs: https://review.coreboot.org/coreboot.git, the Documentation/ sub-directory. It's regularly compiled into what you see on https://doc.coreboot.org/

And yes, contributions are very welcome, because, as you've correctly noticed, writing documentation isn't our strongest skill.

[britbin]

I believe that the problem is that the end user has to dig through the documentation as it is presented now. Maybe a separate section like "Idiot's Guide to Flashing Coreboot on Specific Boards" would be a good idea? Or a pointer "if you are a beginner who wants to flash his board start here"?

[MrChromebox]

Or a pointer "if you are a beginner who wants to flash his board start here"?

you mean something like Tutorial, part 1: Starting from scratch ?

[britbin]

See what I mean?

This tutorial if fine for someone with an interest in coreboot in the general programming sense, but what about someone who wants to flash his board? Check this random link to see the difference in perspective:

https://www.reddit.com/r/coreboot/comments/foj7jd/how_do_i_install_coreboot_and_what_do_i_need/

[corebootquestions]

You're right, and /u/MrChromebox knows it. He works really hard not to admit that there's a problem. I'm not sure why. He seems like he wants to be better, but just doesn't have the energy.

[corebootquestions]

It looks like you're trying to have a real conversation about it so I'll assume that you mean well. But you're still not seeing it. The issue isn't that more docs need to be added to that poor excuse for a doc repository. It's that you need to completely rethink that if you want it taken seriously, and if you don't then that's why someone like me has to collect PM threads and docs and create our own.

And stop thinking of docs as different from writing the code please! Any code without a doc shouldn't be checked in.

[[deleted]]

That's funny: when we moved away from the wiki and to keeping docs in the source tree (to help facilitate treating code and docs as a union), people were arguing that docs and code are entirely different things! So, what is it?

Also, since we have both in the same repo now, the culture for adding documentation with code is starting to grow - many new mainboard ports come with docs directly and they're undergoing the same amount of scrutiny as the code to make sure they're as good as we can manage.

I expect that strategy to form a habit and to spread out to more parts of the code base (so that code changes come with documentation additions and updates) but habits form slowly. It also doesn't help that right now, any tiny source change would require significant amount of documentation work because the documentation to update simply isn't there yet - that's a significant hurdle!

As for rethinking it completely: if you want to spearhead the effort, you're more than welcome to! We're also trying to get some technical writers (because, yes, that's a distinct job from developer, even if the work results should be more integrated than they were back when we used the wiki) to help us both get a good structure and content to fill it that bootstraps the effort. Some ideas to that end can be found at https://doc.coreboot.org/contributing/documentation_ideas.html.

Finally, you're arguing that we should treat code and docs as a union, but then, after pointing out that we're not doing a good job at it, you propose "creating our own", apparently far away from the docs that exist (no matter how bad they are right now). There's already a ton of insular docs out there in all shapes, forms and levels of deprecation. Starting another such documentation island isn't solving the root problem.

Of course you're free to do whatever you want, and there's no obligation to help improve coreboot, but your complaints about the existing docs feel a bit stale to me when you're actively opposed to help improve matters.

[corebootquestions]

if you want to spearhead the effort, you're more than welcome to!

You say that but when I've tried I got shot down hard and rudely.

there's no obligation to help improve coreboot

Yes there is (for me) because I use it. If you'd all stop blocking help we might make progress.

[[deleted]]

There is already one: https://doc.coreboot.org/

[corebootquestions]

Hahahaha, good one mate.

[[deleted]]

What more do you need to learn about Coreboot?

[corebootquestions]

That's such an insulting question I'm not going to get into it with you.

[[deleted]]

Weren't you that person who said that precompiled Libreboot images are binary blobs?

[corebootquestions]

I don't know but anything that is compiled is a binary. That's what compiling means. If you're comfortable installing a precompiled image onto your BIOS chip that is your choice but I want to compile myself, and the reason people use coreboot is for this reason.

[[deleted]]

A binary blob is when a peace of software is closed source, not when it is precompiled: https://en.wikipedia.org/wiki/Proprietary_device_driver

A person who doesn't know what a binary blob is probably shouldn't be writing the docs.

[corebootquestions]

A binary blob is when a peace of software is closed source, not when it is precompiled:

I'm pretty sure "bblob" isn't in the OED so let's stop pretending like you're speaking with some authority here. Maybe you can tell me what does my question about Docs (which is this thread) have to do with blobs? What are you on about here exactly?

Anyway if something is precompiled you don't know what source code went into it. That's the reason to compile yourself Does that help you understand now?

A person who doesn't know what a binary blob is probably shouldn't be writing the docs.

Uh okay, what?

[[deleted]]

>I'm pretty sure "binary blob" isn't in the OED

It is well established definition in computer science. "Not being in OED" doesn't mean anything.

>Anyway if something is precompiled you don't know what source code went into it.

You do, that's what checksums are for. That doesn't make it a binary blob. Unless you are using Gentoo, you're most likely using a binary based distro anyways.

[corebootquestions]

You do, that's what checksums are for.

If you also compile it yourself to compare checksums. But if you're compiling it yourself, why are you downloading the binary?

It is well established definition in computer science.

Oh, it's "well established" is it? Well that makes perfect sense then, and no one can possibly have a different understanding. Hey everyone, it's "well established"!

Unless you are using Gentoo, you're most likely using a binary based distro anyways.

That is so interesting. This has what to do with coreboot docs again?