Ivan's wiki

Site Tools

writing-guide

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
writing-guide [May 25, 2026 at 13:27] – Ivan Janevskiwriting-guide [May 25, 2026 at 13:38] (current) – Ivan Janevski
Line 1: Line 1:
 # Writing guide # Writing guide
-Every article should preferably start with a main section followed by a few paragraphs.+**Writing guide** (this article) is a guide to writing articles in this wiki. 
 + 
 +Every article should preferably start with a main section followed by a few paragraphs. The first paragraph should preferably start with the name of the article in bold (just as it did in this article) followed by a few sentences that further describe the concept. 
 + 
 +## Paragraphs 
 +Paragraphs should describe one main idea in 3-6 sentences. Preferably (though not necessarily so) this idea is better described by an artifact just below the paragraph e.g. a code block, equation or an image. A section should contain 2-5 paragraphs. If there are too many paragraphs, it's fine to open subsections but then they have to contain 2-5 paragraph as well.
  
 ## Sections ## Sections
-Sections should have a certain flavor. For example, if a section is titled "List of concepts related to X" it should only contain a list and no additional description like what the list is for. Similarily, if a section is titled "C++ code illustrating X" it should only contain a code block and preferably no prose. Any additional description can be added in the code comments. Same goes for equations. For sections "Matrix representation". It should only +Sections should have a certain flavor. For example, if a section is titled "List of concepts related to X" it should only contain a list and no additional description. Similarily, if a section is titled "C++ code illustrating X" it should only contain a code block and preferably no prose. Any additional description can be added in the code comments. Same goes for equations. A section like "Equations of X" or "" should only contain LaTeX `$$ ... $$` and little description. It should only 
  
 The first section should preferably always start with a paragraph that starts with the name of the article in **bold** followed by a short description (two-three sentences) of what the concept is. The subsequent paragraphs should expand the concept in the most nautral way.  The first section should preferably always start with a paragraph that starts with the name of the article in **bold** followed by a short description (two-three sentences) of what the concept is. The subsequent paragraphs should expand the concept in the most nautral way. 
  
 ## Code block ## Code block
-A code block is a larger piece of code that+A code block is a larger piece of code that. Preferably all code blocks should be self-contained MVEs (minimum viable examples). At the top there should be a comment block on how to compile and run the code.
  
 ```cpp ```cpp
-// Compile: g++ main.c -o main +// Compile:     g++ main.c -o main 
-// Run:     ./main+// Run:         ./main 
 +// Description: echo "Hello world!"
  
 #include <stdio.h> #include <stdio.h>
Line 21: Line 27:
     return 0;     return 0;
 } }
- 
 ``` ```
 +
 +## Equations
 +Equations should be written in LaTeX. Math symbols like greek letters $\alpha,\beta,\gamma$ are fine to embed directly into paragraphs but heavy-duty equations that involve matrices, integrals, fractions, sums and so on should preferably put in their own line. For example the following is a matrix for Pauli $X$ gate
 +$$X = \begin{pmatrix} 0 & 1 \\ 1 & 0 \end{pmatrix}$$
writing-guide.1779715622.txt.gz · Last modified: by Ivan Janevski