Hi there,
We have a bit of user documentation that shows how to lock a bootblock using WP [1] and what should be taken into account before you do it [2] and thought we can offer it to the upstream (after a bit of editing if there is interest).
[1]: https://github.com/Dasharo/flashrom/blob/wp_integration/Documentation/heads-... [2]: https://github.com/Dasharo/flashrom/blob/wp_integration/Documentation/bootbl...
There is Documentation/ directory in the repository, but I guess Wiki on www.flashrom.org might be more appropriate as it's not documentation for developers. The current format is Markdown, but `pandoc` can convert the files to MediaWiki without issues.
Please check out the docs and say if they can be useful for the project.
Cheers, Sergii
Hello Sergii,
To the question whether the documentation is useful: IMO Yes, I 100% think it is useful. I did a quick read through the links.
Where to put it, this is an interesting question.
The advantage of Documentation/ directory in the repository is that it allows other people (anyone who is interested) to review the text before adding. Because for Documentation/ you basically send a patch and everyone can review. End result gets submitted, and everyone is happy.
For the website, there is no review mechanism, so you either update the page and announce it to everyone, and then people can make corrections post-update. Another way is, after preparing the text you send it to the mailing list and gather feedback, and then later incorporate feedback into the final version of text. This is a more awkward process. But as you said, these docs are for users not developers - so the website seems like a more logical place. I looked through the website, this section seems relevant: https://www.flashrom.org/Documentation#Using_flashrom ?
For the website also, we do have ideas to dramatically upgrade it, but in any case all the content will be migrated over.
I am wondering what other people think, especially if anyone has strong opinions on Documentation/ vs wiki?
On Sat, Oct 8, 2022 at 8:41 AM Sergii Dmytruk sergii.dmytruk@3mdeb.com wrote:
Hi there,
We have a bit of user documentation that shows how to lock a bootblock using WP [1] and what should be taken into account before you do it [2] and thought we can offer it to the upstream (after a bit of editing if there is interest).
There is Documentation/ directory in the repository, but I guess Wiki on www.flashrom.org might be more appropriate as it's not documentation for developers. The current format is Markdown, but `pandoc` can convert the files to MediaWiki without issues.
Please check out the docs and say if they can be useful for the project.
Cheers, Sergii _______________________________________________ flashrom mailing list -- flashrom@flashrom.org To unsubscribe send an email to flashrom-leave@flashrom.org
Hi Anastasia,
On Mon, Oct 10, 2022 at 01:36:38PM +1100, Anastasia Klimchuk wrote:
I looked through the website, this section seems relevant: https://www.flashrom.org/Documentation#Using_flashrom ?
Yes, I agree,
The advantage of Documentation/ directory in the repository is that it allows other people (anyone who is interested) to review the text before adding. Because for Documentation/ you basically send a patch and everyone can review. End result gets submitted, and everyone is happy.
Another option is to use Gerrit for the review, but then abandon the change, convert to Wiki format and publish final result on the website.
Regards, Sergii
Hi all,
Having this documentation added to the flashrom Wiki sounds like a great idea. Thank you for the proposal!
On Mon, Oct 10, 2022 at 12:11 PM Sergii Dmytruk sergii.dmytruk@3mdeb.com wrote:
Hi Anastasia,
On Mon, Oct 10, 2022 at 01:36:38PM +1100, Anastasia Klimchuk wrote:
I looked through the website, this section seems relevant: https://www.flashrom.org/Documentation#Using_flashrom ?
Yes, I agree,
It seems to be a suitable place, yes. The text can be moved elsewhere if need be in the future, anyway.
The advantage of Documentation/ directory in the repository is that it allows other people (anyone who is interested) to review the text before adding. Because for Documentation/ you basically send a patch and everyone can review. End result gets submitted, and everyone is happy.
Another option is to use Gerrit for the review, but then abandon the change, convert to Wiki format and publish final result on the website.
Reviewing Wiki changes on the mailing list is a reasonable option as well, especially if commenting inline. Top-posting is generally frowned upon on mailing lists (although having an introduction section before replying to specific parts is fine, see this very email).
Regards, Sergii
Best regards, Angel
Hi Angel,
On Mon, Oct 10, 2022 at 12:22:10PM +0000, Angel Pons wrote:
On Mon, Oct 10, 2022 at 12:11 PM Sergii Dmytruk sergii.dmytruk@3mdeb.com wrote:
On Mon, Oct 10, 2022 at 01:36:38PM +1100, Anastasia Klimchuk wrote:
I looked through the website, this section seems relevant: https://www.flashrom.org/Documentation#Using_flashrom ?
Yes, I agree,
It seems to be a suitable place, yes. The text can be moved elsewhere if need be in the future, anyway.
I thought these can be two separate pages with https://www.flashrom.org/Documentation#Using_flashrom listing links to them. It's all on the same topic, but one is a caution for those who decide to write-protect part of their chip and the second one is a usage example/tutorial. Embedding it all in one page will make it hard to find whatever else is one the same page.
Reviewing Wiki changes on the mailing list is a reasonable option as well, especially if commenting inline. Top-posting is generally frowned upon on mailing lists (although having an introduction section before replying to specific parts is fine, see this very email).
OK, I'll make another thread for review then.
Best regards, Sergii
-
Anastasia Klimchuk -
Angel Pons -
Sergii Dmytruk