diff --git a/specs/altair/beacon-chain.md b/specs/altair/beacon-chain.md
index 5426b9cf0..26fce7fdd 100644
--- a/specs/altair/beacon-chain.md
+++ b/specs/altair/beacon-chain.md
@@ -276,7 +276,8 @@ def has_flag(flags: ParticipationFlags, flag_index: int) -> bool:
 ```python
 def get_sync_committee_indices(state: BeaconState, epoch: Epoch) -> Sequence[ValidatorIndex]:
     """
-    Return the sequence of sync committee indices (which may include duplicate indices) for a given state and epoch.
+    Return the sequence of sync committee indices (which may include duplicate indices)
+    for a given ``state`` and ``epoch``.
     """
     MAX_RANDOM_BYTE = 2**8 - 1
     base_epoch = Epoch((max(epoch // EPOCHS_PER_SYNC_COMMITTEE_PERIOD, 1) - 1) * EPOCHS_PER_SYNC_COMMITTEE_PERIOD)
@@ -301,7 +302,7 @@ def get_sync_committee_indices(state: BeaconState, epoch: Epoch) -> Sequence[Val
 ```python
 def get_sync_committee(state: BeaconState, epoch: Epoch) -> SyncCommittee:
     """
-    Return the sync committee for a given state and epoch.
+    Return the sync committee for a given ``state`` and ``epoch``.
     """
     indices = get_sync_committee_indices(state, epoch)
     pubkeys = [state.validators[index].pubkey for index in indices]
diff --git a/specs/sharding/beacon-chain.md b/specs/sharding/beacon-chain.md
index 2ddcc6a82..6fd83c9cf 100644
--- a/specs/sharding/beacon-chain.md
+++ b/specs/sharding/beacon-chain.md
@@ -166,7 +166,7 @@ class BeaconBlockBody(merge.BeaconBlockBody):  # [extends The Merge block body]
 ### `BeaconState`
 
 ```python
-class BeaconState(merge.BeaconState):  # [extends The Merge block body]
+class BeaconState(merge.BeaconState):  # [extends The Merge state]
     # [Updated fields]
     previous_epoch_attestations: List[PendingAttestation, MAX_ATTESTATIONS * SLOTS_PER_EPOCH]
     current_epoch_attestations: List[PendingAttestation, MAX_ATTESTATIONS * SLOTS_PER_EPOCH]