search

sinara-hw / Sayma_AMC

AMC FPGA carrier board with FMC, dual SFP and RTM
8 stars 6 forks source link

PCB modifications refactor #151

Closed jbqubit closed 4 years ago

jbqubit commented 4 years ago

I refactored the PCB Modifications page. Needs sign off by @marmeladapk. In particular as to which release is the reference point for that page. See comment on the wiki.

jbqubit commented 4 years ago

Before refactor. beforerefactor

marmeladapk commented 4 years ago

@jbqubit, I'm afraid that your refactors made this table completely unreadable and more difficult to maintain than it should be (and it's not only my opinion). I'd be in favour to keep the old format and just add information which boards base on which release+other readability improvements.

jbqubit commented 4 years ago

The information content in the old version and the refactored version are the same. The refactored version follows the coding practice of not repeating identical text string throughout code. It is also much easier to extend and annotate changes that apply to more than one board without errors creeping in. For example, there's a natural place to explain "R91->100K."

Definitely think we need to state the baseline release. Do you agree with "[v2.0rc8]"?

marmeladapk commented 4 years ago

First two Saymas were based on rc8, rest on 2.0.1 (which was a BoM change).

The information content in the old version and the refactored version are the same. The refactored version follows the coding practice of not repeating identical text string throughout code.

I'm not saying it isn't. But reading and writing isn't programming and repeating R91->100K is way easier to interpret than looking up what does M5 or C0 mean, especially since they do not fit in one screen.

Right now, when looking at the table I only see a bunch of repeated "yes" which tell me nothing unless I look up each item individually. Even worse to maintain are things that appear only in one board, as they clutter "namespace" while these are mostly notes.

We don't have 300 boards to maintain in this table. Let's not complicate my life for the sake of good coding practice applied to documentation.

marmeladapk commented 4 years ago

@jbqubit Please check if this format is ok.

jbqubit commented 4 years ago

Thanks for the update. Looks easier to read than what I proposed.

marmeladapk commented 4 years ago

@jbqubit We have some space for ~2 additional columns in the first table. Do you have any idea for information that would be useful to cross-compare between boards?