search

tigard-tools / tigard

An FTDI FT2232H-based multi-protocol tool for hardware hacking
Other
592 stars 72 forks source link

refactor readme #37

Open securelyfitz opened 3 years ago

securelyfitz commented 3 years ago

Previously considered refactoring the readme into separate readmes per interface, but have gotten lots of feedback on the 'flat' readme format, so will keep it.

I added a toc in 1e7971c34c387b02b1f95d27a5c4665b8327651b (first generated with doctoc, but manually tweaked for brevity - it should be rather static so no need to automate updates)

Originally the 'usage' was supposed to be broken down by header, but became a list of protocols instead. Then, the 'pinouts' was supposed to be a raw pinout list, but became a protocol specific list instead.

  1. should probably merge the 'pinout' sections into the corresponding 'usage' sections
  2. may still be worth adding a combined grand unified pinout map (though this might still be best under the LA heading)
fharding1 commented 3 years ago

I'll add that I'm pro flat README :grin: I think the Table of Contents works great.

hamid-elaosta commented 3 years ago

Just to add an extra opinion.

I found it relatively simple to convert the single README to an ebook as a little reference for on my e-Reader, only needed minor post-processing to fix the code blocks and add a ToC using Calibre, the "#" headers become chapters and sections etc.

Relative image URLs would help a bit too but not a big deal.

IMG_20210403_114612__01.jpg

colinoflynn commented 3 years ago

Love the flat README - as is it's pretty brief on each topic I think, so still hitting the README feel. If you start adding multiple examples to each section could see what you mean about breaking it out.

If you want a bit of both, you can setup github actions that do fancier processing on doc commits. For example with https://github.com/newaetech/chipwhisperer-target-cw308t we have a GH action that copies all the README.md files in the individual subdirectory into another repo with different names & then builds the doc output with mkdocs to https://rtfm.newae.com . You could probably break out individual .md files if you wanted but still auto-merge them into one flat .md file for those who want a single file. But it's a lot more hassle than you've got now ;-)

skochinsky commented 3 years ago

I would love to have a downloadable, self-contained PDF or EPUB that can be viewed offline.

fharding1 commented 3 years ago

I would love to have a downloadable, self-contained PDF or EPUB that can be viewed offline.

Pandoc is pretty good at converting markdown into a readable PDF/EPUB. I don't like the idea of keeping generated binary PDF/EPUB files in the repository, but perhaps this is something we could include in releases like we do with the schematic PDFs.

securelyfitz commented 3 years ago

Agree with @fharding1, i like including a pdf/epub in the release bundles. We're overdue to release the v1.1 bundle, but i have a few readme more additions i should include before we roll that.